GoDNS
A dynamic DNS client tool, supports DNSPod & HE.net, written in Go
About GoDNS
This large README is shown as a plain-text preview. Read the full README at the source
```text
██████╗ ██████╗ ██████╗ ███╗ ██╗███████╗
██╔════╝ ██╔═══██╗██╔══██╗████╗ ██║██╔════╝
██║ ███╗██║ ██║██║ ██║██╔██╗ ██║███████╗
██║ ██║██║ ██║██║ ██║██║╚██╗██║╚════██║
╚██████╔╝╚██████╔╝██████╔╝██║ ╚████║███████║
╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝
```
[![Apache licensed][9]][10] [![Docker][3]][4] [![Go Report Card][11]][12] [![GoDoc][13]][14] [![Homebrew][15]][16]
[3]: https://img.shields.io/docker/image-size/timothyye/godns/latest
[4]: https://hub.docker.com/r/timothyye/godns
[9]: https://img.shields.io/badge/license-Apache-blue.svg
[10]: LICENSE
[11]: https://goreportcard.com/badge/github.com/timothyye/godns
[12]: https://goreportcard.com/report/github.com/timothyye/godns
[13]: https://godoc.org/github.com/TimothyYe/godns?status.svg
[14]: https://godoc.org/github.com/TimothyYe/godns
[15]: https://img.shields.io/homebrew/v/godns
[16]: https://formulae.brew.sh/formula/godns
[GoDNS](https://github.com/TimothyYe/godns) is a self-hosted dynamic DNS (DDNS) client with multi-provider support and a built-in web panel. It is a rewrite in [Go](https://golang.org) of my early [DynDNS](https://github.com/TimothyYe/DynDNS) open-source project.
[查看中文帮助文档](README_CN.md)
## Hosted version
If you want a managed DDNS service instead of self-hosting GoDNS yourself, try [godns.app](https://godns.app).
It is a hosted option for users who want DDNS without running their own server, managing DNS manually, or even owning a domain in advance.
Below is the built-in web panel of the open-source GoDNS project:
<img src="https://github.com/TimothyYe/godns/blob/master/assets/snapshots/web-panel.jpg?raw=true" />
- [Supported DNS Providers](#supported-dns-providers)
- [Quick Start](#quick-start)
- [Supported Platforms](#supported-platforms)
- [Self-hosting Pre-conditions](#self-hosting-pre-conditions)
- [Installation](#installation)
- [Configuration](#configuration)
- [Web Panel](#web-panel)
- [Running GoDNS](#running-godns)
- [Contributing](#contributing)
---
## Supported DNS Providers
| Provider | IPv4 support | IPv6 support | Root Domain | Subdomains |
| ------------------------------------- | :----------------: | :----------------: | :----------------: | :----------------: |
| [Cloudflare][cloudflare] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [DigitalOcean][digitalocean] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Google Domains][google.domains] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [DNSPod][dnspod] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Dynv6][dynv6] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [HE.net (Hurricane Electric)][he.net] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [AliDNS][alidns] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [DuckDNS][duckdns] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [Dreamhost][dreamhost] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [No-IP][no-ip] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [Scaleway][scaleway] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Linode][linode] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Strato][strato] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [LoopiaSE][loopiase] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [Infomaniak][infomaniak] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [Hetzner][hetzner] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [OVH][ovh] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [Porkbun][porkbun] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| [Dynu][dynu] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [IONOS][ionos] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [TransIP][transip] | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
| [name.com][namecom] | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
[cloudflare]: https://cloudflare.com
[digitalocean]: https://digitalocean.com
[google.domains]: https://domains.google
[dnspod]: https://www.dnspod.cn
[dynv6]: https://dynv6.com
[he.net]: https://dns.he.net
[alidns]: https://help.aliyun.com/product/29697.html
[duckdns]: https://www.duckdns.org
[dreamhost]: https://www.dreamhost.com
[no-ip]: https://www.noip.com
[scaleway]: https://www.scaleway.com/
[linode]: https://www.linode.com
[strato]: https://strato.de
[loopiase]: https://www.loopia.se/
[infomaniak]: https://www.infomaniak.com/
[hetzner]: https://hetzner.com/
[ovh]: https://www.ovh.com
[porkbun]: https://porkbun.com/
[dynu]: https://www.dynu.com/
[ionos]: https://www.ionos.com/
[transip]: https://www.transip.net/
[namecom]: https://www.name.com/
Tip: You can follow this [issue](https://github.com/TimothyYe/godns/issues/76) to view the current status of DDNS for root domains.
## Quick Start
Choose the path that fits you best:
- Want a managed service with no self-hosting: use [godns.app](https://godns.app).
- Want the fastest self-hosted setup: download a binary from [releases](https://github.com/TimothyYe/godns/releases).
- Want to run it in a container: jump to [As a Docker container](#as-a-docker-container).
- Want to build from source: see [Installation](#installation).
## Supported Platforms
- Linux
- MacOS
- ARM Linux (Raspberry Pi, etc.)
- Windows
- MIPS32 platform
To compile binaries for MIPS (mips or mipsle), run:
```bash
GOOS=linux GOARCH=mips/mipsle GOMIPS=softfloat go build -a
```
The binary can run on routers as well.
## Self-hosting Pre-conditions
To self-host GoDNS, it is assumed:
- You registered (now own) a domain
- Domain was delegated to a supported [DNS provider](#supported-dns-providers) (i.e. it has nameserver `NS` records pointing at a supported provider)
Alternatively, you can sign in to [DuckDNS](https://www.duckdns.org) (with a social account) and get a subdomain on the duckdns.org domain for free.
## Installation
Choose one of the following installation methods:
- Install with [Homebrew](https://brew.sh) (macOS / Linux):
```bash
brew install godns
```
- Download a compiled binary from [releases](https://github.com/TimothyYe/godns/releases).
- Use the Docker image described in [As a Docker container](#as-a-docker-container).
- Build from source:
```bash
cd cmd/godns # go to the GoDNS directory
go mod download # get dependencies
go build # build
```
## Usage
Print usage/help by running:
```bash
$ ./godns -h
Usage of ./godns:
-c string
Specify a config file (default "./config.json")
-h Show help
```
## Configuration
### Overview
- Make a copy of [config_sample.json](configs/config_sample.json) and name it as `config.json`, or make a copy of [config_sample.yaml](configs/config_sample.yaml) and name it as `config.yaml`.
- Configure your provider, domain/subdomain info, credentials, etc.
- Configure a notification medium (e.g. SMTP to receive emails) to get notified when your IP address changes
- Place the file in the same directory of GoDNS or use the `-c=path/to/your/file.json` option
### Multi-Provider Support
🆕 **GoDNS now supports multiple DNS providers simultaneously!**
You can now configure domains from different DNS providers in a single configuration file, allowing you to:
- Manage domains across multiple DNS services (Cloudflare, DNSPod, DigitalOcean, etc.)
- Use provider-specific credentials for each service
- Maintain full backward compatibility with existing single-provider configurations
📖 **[View the complete Multi-Provider Configuration Guide](MULTI_PROVIDER.md)** for detailed setup instructions and examples.
### Configuration file format
GoDNS supports 2 different configuration file formats:
- JSON
- YAML
By default, GoDNS uses `JSON` config file. However, you can specify to use the `YAML` format via: `./godns -c /path/to/config.yaml`
### Dynamic loading of configuration
GoDNS supports dynamic loading of configuration. If you modify the configuration file, GoDNS will automatically reload the configuration and apply the changes.
### Configuration properties
- `provider` — One of the [supported provider to use](#supported-dns-providers): `Cloudflare`, `Google`, `DNSPod`, `AliDNS`, `HE`, `DuckDNS` or `Dreamhost`.
- `email` — Email or account name of the DNS provider.
- `password` — Password of the DNS provider.
- `login_token` — API token of the DNS provider.
- `domains` — Domains list, with your subdomains.
- `ip_urls` — A URL array for fetching one's public IPv4 address.
- `ipv6_urls` — A URL array for fetching one's public IPv6 address.
- `ip_type` — Switch deciding if IPv4 or IPv6 should be used (when [supported](#supported-dns-providers)). Available values: `IPv4` or `IPv6`.
- `interval` — How often (in seconds) the public IP should be updated.
- `socks5_proxy` — Socks5 proxy server.
- `resolver` — Address of a public DNS server to use. For instance to use [Google's public DNS](https://developers.google.com/speed/public-dns/docs/using), you can set `8.8.8.8` when using GoDNS in IPv4 mode or `2001:4860:4860::8888` in IPv6 mode.
- `skip_ssl_verify` - Skip verification of SSL certificates for https requests.
### Update root domain
By simply putting `@` into `sub_domains`, for example:
```json
"domains": [{
"domain_name": "example.com",
"sub_domains": ["@"]
}]
```
### Configuration examples
#### Cloudflare
For Cloudflare, you need to provide the email & Global API Key as a password (or to use the API token) and configure all the domains & subdomains.
By setting the option `proxied = true`, the record receives the performance and security benefits of Cloudflare. This option is only available for Cloudflare.
<details>
<summary>Using email & Global API Key</summary>
```json
{
"provider": "Cloudflare",
"email": "[email protected]",
"password": "Global API Key",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": "",
"proxied": false
}
```
</details>
<details>
<summary>Using the API Token</summary>
```json
{
"provider": "Cloudflare",
"login_token": "API Token",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### DNSPod
For DNSPod, you need to provide your API Token(you can create it [here](https://www.dnspod.cn/console/user/security)), and config all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "DNSPod",
"login_token": "your_id,your_token",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### DigitalOcean
For DigitalOcean, you need to provide an API Token with the `domain` scopes (you can create it [here](https://cloud.digitalocean.com/account/api/tokens/new)), and config all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "DigitalOcean",
"login_token": "dop_v1_00112233445566778899aabbccddeeff",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["@", "www"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300
}
```
</details>
#### Dreamhost
For Dreamhost, you need to provide your API Token(you can create it [here](https://panel.dreamhost.com/?tree=home.api)), and config all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "Dreamhost",
"login_token": "your_api_key",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"resolver": "ns1.dreamhost.com",
"socks5_proxy": ""
}
```
</details>
#### Dynv6
For Dynv6, only need to provide the `token`, config 1 default domain & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "Dynv6",
"password": "",
"login_token": "1234567ABCDEFGabcdefg123456789",
"domains": [
{
"domain_name": "dynv6.net",
"sub_domains": ["myname"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### Google Domains
For Google Domains, you need to provide email & password, and config all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "Google",
"email": "Your_Username",
"password": "Your_Password",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### AliDNS
For AliDNS, you need to provide `AccessKeyID` & `AccessKeySecret` as `email` & `password`, and config all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "AliDNS",
"email": "AccessKeyID",
"password": "AccessKeySecret",
"login_token": "",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### DuckDNS
For DuckDNS, the only thing needed is to provide the `token`, config 1 default domain & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "DuckDNS",
"password": "",
"login_token": "3aaaaaaaa-f411-4198-a5dc-8381cac61b87",
"domains": [
{
"domain_name": "www.duckdns.org",
"sub_domains": ["myname"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### No-IP
<details>
<summary>Example</summary>
```json
{
"provider": "NoIP",
"email": "[email protected]",
"password": "YourPassword",
"domains": [
{
"domain_name": "ddns.net",
"sub_domains": ["timothyye6"]
}
],
"ip_type": "IPv4",
"ip_urls": ["https://api.ip.sb/ip"],
"resolver": "8.8.8.8",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
#### HE.net
For HE, email is not needed, just fill in the DDNS key as a password, and configure all the domains & subdomains.
<details>
<summary>Example</summary>
```json
{
"provider": "HE",
"password": "Your DDNS Key",
"login_token": "",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "test"]
},
{
"domain_name": "example2.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
```
</details>
<details>
<summary>Provider configuration</summary>
Add a new "A record" and make sure that "Enable entry for dynamic dns" is checked:
<img src="assets/snapshots/he1.png" width="640" />
Fill in your own DDNS key or generate a random DDNS key for this newly created "A record":
<img src="assets/snapshots/he2.png" width="640" />
Remember the DDNS key and set it in the `password` property in the configuration file.
**NOTICE**: If you have multiple domains or subdomains, make sure their DDNS key are the same.
</details>
#### Scaleway
For Scaleway, you need to provide an API Secret Key as the `login_token` ([How to generate an API key](https://www.scaleway.com/en/docs/generate-api-keys/)), and configure the domains and subdomains. `domain_name` should equal a DNS zone, or the root domain in Scaleway. TTL for the DNS records will be set to the `interval` value. Make sure `A` or `AAAA` records exist for the relevant sub domains, these can be set up in the [Scaleway console](https://www.scaleway.com/en/docs/scaleway-dns/#-Managing-Records).
<details>
<summary>Example</summary>
```json
{
"provider": "Scaleway",
"login_token": "API Secret Key",
"domains": [
{
"domain_name": "example.com",
"sub_domains": ["www", "@"]
},
{
"domain_name": "samplednszone.example.com",
"sub_domains": ["www", "test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300
}
```
</details>
#### Linode
To authenticate with the Linode API you will need to provide a Personal Access Token with "Read/Write" access on the "Domain" scope. Linode has [a help page about creating access tokens](https://www.linode.com/docs/guides/getting-started-with-the-linode-api/). Pass this token into the `login_token` field of the config file.
The `domain_name` field of the config file must be the name of an existing Domain managed by Linode. Linode has [a help page about adding domains](https://www.linode.com/docs/guides/dns-manager/). The GoDNS Linode handler will not create domains automatically but will create subdomains automatically.
The GoDNS Linode handler currently uses a fixed TTL of 30 seconds for Linode DNS records.
<details>
<summary>Example</summary>
```json
{
"provider": "Linode",
"login_token": ${PERSONAL_ACCESS_TOKEN},
"domains": [{
"domain_name": "example.com",
"sub_domains": ["www","@"]
},{
"domain_name": "samplednszone.example.com",
"sub_domains": ["www","test"]
}
],
"resolver": "8.8.8.8",
"ip_urls": ["https://api.ip.sb/ip"],
"ip_type": "IPv4",
"interval": 300
}
```
</details>
#### Strato
For Strato, you need to provide email & password and configure all the domains & subdomains.
More Info: [German](https://www.strato.de/faq/hosting/so-einfach-richten-sie-dyndns-fuer-ihre-domains-ein/) [English](https://www.strato-hosting.co.uk/faq/hosting/this-is-how-easy-it-is-to-set-up-dyndns-for-your-domains/)
<details>
<summary>Example</summary>
```json
{
"provider": "strato",
"password": "Your_Password",
"domains": [
{
"domain_name": "example.com",Frequently Asked Questions
What is GoDNS?
GoDNS is a Dynamic DNS library for the Go programming language. A dynamic DNS client tool, supports DNSPod & HE.net, written in Go
How many GitHub stars does GoDNS have?
GoDNS has 1,781 GitHub stars in the directory's latest synchronization.
How do I install GoDNS?
Install GoDNS with the Go module system using `go get timothyye/godns`. Check the repository for the current installation instructions.
What category does GoDNS belong to?
GoDNS is listed under Dynamic DNS, specifically Dynamic DNS.