godns

 ██████╗  ██████╗ ██████╗ ███╗   ██╗███████╗
██╔════╝ ██╔═══██╗██╔══██╗████╗  ██║██╔════╝
██║  ███╗██║   ██║██║  ██║██╔██╗ ██║███████╗
██║   ██║██║   ██║██║  ██║██║╚██╗██║╚════██║
╚██████╔╝╚██████╔╝██████╔╝██║ ╚████║███████║
 ╚═════╝  ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝

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 of my early DynDNS open-source project.

查看中文帮助文档

Hosted version

If you want a managed DDNS service instead of self-hosting GoDNS yourself, try 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:

• Supported DNS Providers
• Quick Start
• Supported Platforms
• Self-hosting Pre-conditions
• Installation
• Configuration
• Web Panel
• Running GoDNS
• Contributing

Supported DNS Providers

Tip: You can follow this issue 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.
• Want the fastest self-hosted setup: download a binary from releases.
• Want to run it in a container: jump to As a Docker container.
• Want to build from source: see 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 (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

Choose one of the following installation methods:

• Install with Homebrew (macOS / Linux):

brew install godns

• Download a compiled binary from releases.
• Use the Docker image described in As a Docker container.
• Build from source:

cd cmd/godns        # go to the GoDNS directory
go mod download     # get dependencies
go build            # build

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 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 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: 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). 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, 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:

"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.

{
  "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
}

{
  "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.

{
  "provider": "DNSPod",
  "login_token": "your_id,your_token",
  "domains": [
    {