██████╗ ██████╗ ██████╗ ███╗ ██╗███████╗
██╔════╝ ██╔═══██╗██╔══██╗████╗ ██║██╔════╝
██║ ███╗██║ ██║██║ ██║██╔██╗ ██║███████╗
██║ ██║██║ ██║██║ ██║██║╚██╗██║╚════██║
╚██████╔╝╚██████╔╝██████╔╝██║ ╚████║███████║
╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝
GoDNS is a dynamic DNS (DDNS) client tool. It is a rewrite in Go of my early DynDNS open source project.
- Supported DNS Providers
- Supported Platforms
- Pre-conditions
- Installation
- Usage
- Configuration
- Web Panel
- Running GoDNS
- Contributing
- Special Thanks
Supported DNS Providers
Provider | IPv4 support | IPv6 support | Root Domain | Subdomains |
---|---|---|---|---|
Cloudflare | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
DigitalOcean | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
Google Domains | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
DNSPod | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
Dynv6 | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
HE.net (Hurricane Electric) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
AliDNS | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
DuckDNS | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Dreamhost | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
No-IP | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Scaleway | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
Linode | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
Strato | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
LoopiaSE | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Infomaniak | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Hetzner | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
OVH | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Dynu | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
IONOS | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
Tip: You can follow this issue to view the current status of DDNS for root domains.
Supported Platforms
- Linux
- MacOS
- ARM Linux (Raspberry Pi, etc.)
- Windows
-
MIPS32 platform
To compile binaries for MIPS (mips or mipsle), run:
GOOS=linux GOARCH=mips/mipsle GOMIPS=softfloat go build -a
The binary can run on routers as well.
Pre-conditions
To use GoDNS, it is assumed:
- You registered (now own) a domain
- Domain was delegated to a supported DNS provider (i.e. it has nameserver
NS
records pointing at a supported provider)
Alternatively, you can sign in to DuckDNS (with a social account) and get a subdomain on the duckdns.org domain for free.
Installation
Build GoDNS by running (from the root of the repository):
cd cmd/godns # go to the GoDNS directory
go mod download # get dependencies
go build # build
You can also download a compiled binary from the releases.
Usage
Print usage/help by running:
$ ./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 and name it as
config.json
, or make a copy of config_sample.yaml and name it asconfig.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
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:Cloudflare
,Google
,DNSPod
,AliDNS
,HE
,DuckDNS
orDreamhost
.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 sub domains.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). Available values:IPv4
orIPv6
.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, you can set8.8.8.8
when using GoDNS in IPv4 mode or2001: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:
"domains": [{
"domain_name": "example.com",
"sub_domains": ["@"]
}]
Configuration examples
Cloudflare
For Cloudflare, you need to provide the email & Global API Key as password (or to use the API token) and config all the domains & subdomains.
By setting the option proxied = true
, the record is receiving the performance and security benefits of Cloudflare. This option is only available for Cloudflare.
Using email & Global API Key
```json { "provider": "Cloudflare", "email": "you@example.com", "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 } ```Using the API Token
```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": "" } ```DNSPod
For DNSPod, you need to provide your API Token(you can create it here), and config all the domains & subdomains.
Example
```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": "" } ```DigitalOcean
For DigitalOcean, you need to provide a API Token with the domain
scopes (you can create it here), and config all the domains & subdomains.
Example
```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 } ```Dreamhost
For Dreamhost, you need to provide your API Token(you can create it here), and config all the domains & subdomains.
Example
```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": "" } ```Dynv6
For Dynv6, only need to provide the token
, config 1 default domain & subdomains.
Example
```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": "" } ```Google Domains
For Google Domains, you need to provide email & password, and config all the domains & subdomains.
Example
```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": "" } ```AliDNS
For AliDNS, you need to provide AccessKeyID
& AccessKeySecret
as email
& password
, and config all the domains & subdomains.
Example
```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": "" } ```DuckDNS
For DuckDNS, the only thing needed is to provide the token
, config 1 default domain & subdomains.
Example
```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": "" } ```No-IP
Example
```json { "provider": "NoIP", "email": "mail@example.com", "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": "" } ```HE.net
For HE, email is not needed, just fill the DDNS key as password, and config all the domains & subdomains.
Example
```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": "" } ```Provider configuration
Add a new "A record" and make sure that "Enable entry for dynamic dns" is checked: Fill in your own DDNS key or generate a random DDNS key for this new created "A record": 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.Scaleway
For Scaleway, you need to provide an API Secret Key as the login_token
(How to generate an API key), 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.
Example
```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 } ```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. 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. 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.
Example
```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 } ```Strato
For Strato, you need to provide email & password, and config all the domains & subdomains. More Info: German English
Example
```json { "provider": "strato", "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": "" } ```LoopiaSE
For LoopiaSE, you need to provide username & password, and config all the domains & subdomains. More info: Swedish
Example
```json { "provider": "LoopiaSE", "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": "" } ```Infomaniak
For Infomaniak, you need to provide username & password, and config all the domains & subdomains. More info: English
Example
```json { "provider": "Infomaniak", "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": "" } ```Hetzner
For Hetzner, you have to create an access token. This can be done in the DNS-Console. (Person Icon in the top left corner –> API Tokens) Notice: If a domain has multiple Records only the first Record will be updated. Make shure there is just one record.