中文文档

A domain WHOIS query tool implemented in Golang, supporting WHOIS information queries for all publicly queryable TLD domains, IPv4/v6, and ASN.

In compliance with ICANN's "Temporary Specification for gTLD Registration Data" and the EU's "General Data Protection Regulation" (GDPR), when querying domain information, the program only returns essential information (see response examples below) and does not return the owner's contact information, address, phone number, email, and other personal fields.

Demo Sites:

• https://whois.ddnsip.cn
• https://whois.mmoke.com By immoke

# Install Redis
docker run -d --name redis -p 6379:6379 redis:latest
# Run whois
docker run -d --name whois -p 8043:8043 --link redis:redis jinzeyang/whois

You can download the binary files for your platform from the Release page.

git clone https://github.com/KincaidYang/whois.git
cd whois
go build

This program requires Redis service support. You can refer to https://redis.io/docs/install/install-redis/install-redis-on-linux/ for installation.

vim config.yaml

redis:
  addr: "redis:6379"           # Redis server address
  password: ""                 # Redis password, leave empty if none
  db: 0                        # Redis database number
cacheExpiration: 3600          # Cache expiration time in seconds

# Advanced cache configuration (optional, new feature)
cache:
  requireRedis: false          # false=allow fallback to memory cache when Redis fails, true=Redis must be available or program exits
  memoryMaxSize: 10000         # Maximum entries in memory cache (default: 10000)
  memoryCleanInterval: 300     # Memory cache cleanup interval in seconds (default: 300)

port: 8043                     # Server listening port
rateLimit: 50                  # Concurrency limit for upstream WHOIS server requests

# Proxy configuration (optional)
ProxyServer: "http://127.0.0.1:8080"  # Proxy server address
ProxySuffixes:                         # TLD suffixes that need proxy, leave empty to disable
ProxyUsername: ""                      # Proxy server username (if authentication required)
ProxyPassword: ""                      # Proxy server password (if authentication required)

Configuration Notes:

• Redis Configuration: Redis is recommended for better performance and multi-instance cache sharing
• Cache Expiration: Adjust based on query frequency, 3600 seconds recommended
• Concurrency Limit: Controls request frequency to upstream servers to avoid rate limiting
• Proxy Configuration: Some TLDs may require proxy access

⚠️ Warning: The rate limit applies to requests from this program to WHOIS servers, not requests from users to this program. For example, if you set the limit to 50, the program will not exceed 50 requests/second to registry WHOIS servers, but user requests to this program are unlimited. Please use Nginx or other tools to rate-limit this program to prevent malicious requests.

./whois

Note: The program listens on port 8043 by default.

The service provides the following health check endpoints:

Endpoint	Description
GET /health	Liveness probe - returns 200 if service is running
GET /ready	Readiness probe - checks cache and capacity status
GET /info	Runtime information - version, uptime, Go version, etc.

You can use systemd or other tools to set up this program as a daemon process to auto-start after system reboot.

vim /etc/systemd/system/whois.service

[Unit]
Description=whois
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/path/to/whois/whois
WorkingDirectory=/path/to/whois
Restart=on-failure

[Install]
WantedBy=multi-user.target

GET requests

After deployment, access http://ip:port/domain-or-ip-or-asn via browser. Default port is 8043, e.g., http://1.2.3.4:8043/example.com

curl http://localhost:8043/example.com

Response:

{
    "Domain Name": "EXAMPLE.COM",
    "Registrar": "RESERVED-Internet Assigned Numbers Authority",
    "Registrar IANA ID": "376",
    "Domain Status": [
        "client delete prohibited",
        "client transfer prohibited",
        "client update prohibited"
    ],
    "Creation Date": "1995-08-14T04:00:00Z",
    "Registry Expiry Date": "2024-08-13T04:00:00Z",
    "Updated Date": "2023-08-14T07:01:38Z",
    "Name Server": [
        "A.IANA-SERVERS.NET",
        "B.IANA-SERVERS.NET"
    ],
    "DNSSEC": "signedDelegation",
    "DNSSEC DS Data": "370 13 2 BE74359954660069D5C63D200C39F5603827D7DD02B56F120EE9F3A86764247C",
    "Last Update of Database": "2024-01-16T10:26:40Z"
}

curl http://localhost:8043/1.12.34.56

Response:

{
  "IP Network": "1.12.0.0 - 1.15.255.255",
  "Address Range": "1.12.0.0 - 1.15.255.255",
  "Network Name": "TencentCloud",
  "CIDR": "1.12.0.0/14",
  "Network Type": "ALLOCATED PORTABLE",
  "Country": "CN",
  "Status": ["active"],
  "Creation Date": "2010-05-10T22:46:58Z",
  "Updated Date": "2023-11-28T00:51:33Z"
}

curl http://localhost:8043/2402:4e00::

Response:

{
  "IP Network": "2402:4e00::/32",
  "Address Range": "2402:4e00:: - 2402:4e00:ffff:ffff:ffff:ffff:ffff:ffff",
  "Network Name": "TencentCloud",
  "CIDR": "2402:4e00::/32",
  "Network Type": "ALLOCATED PORTABLE",
  "Country": "CN",
  "Status": ["active"],
  "Creation Date": "2010-05-12T23:13:32Z",
  "Updated Date": "2024-01-31T06:27:10Z"
}

curl http://localhost:8043/ASN205794
curl http://localhost:8043/AS205794
curl http://localhost:8043/205794

⚠ Case-insensitive

Response:

{
  "AS Number": "AS205794",
  "Network Name": "RTTW-AS",
  "Status": ["active"],
  "Creation Date": "2022-04-14T12:24:55Z",
  "Updated Date": "2024-03-21T07:27:44Z",
  "remarks": [
    {
      "title": "",
      "description": [
        "https://as205794.net/",
        "Geofeed https://geo.as205794.net/geofeed.csv",
        "Looking Glass https://lg.as205794.net/"
      ]
    }
  ]
}

The program queries WHOIS information from registries primarily using the RDAP protocol. However, since most ccTLDs do not support RDAP, the program will format and return the original WHOIS information as JSON data. Due to limited resources, not all ccTLD suffixes have been adapted, and the program may directly return text data. If your commonly used suffix is not covered, please submit an Issue or contribute matching rules to the whois_parsers.go file. Thank you!

You can determine the response data format by checking the content-type header.

This project uses the following Go standard libraries:

• bytes: Functions for byte slice operations
• context: Context type for passing deadlines, cancellation signals, and request-scoped values
• encoding/json: JSON encoding and decoding
• errors: Error creation and manipulation
• fmt: Formatted I/O functions
• io: I/O primitives
• log: Simple logging service
• net: Network I/O primitives
• net/http: HTTP client and server implementation
• os: OS functionality
• os/signal: OS signal handling
• regexp: Regular expression search
• strconv: String conversion functions
• strings: String manipulation functions
• sync: Basic synchronization primitives
• syscall: Low-level OS calls
• time: Time measurement and display

This project also uses the following third-party libraries:

• github.com/redis/go-redis/v9: Redis client for Go
• golang.org/x/net/idna: IDNA (Internationalized Domain Names in Applications) implementation
• golang.org/x/net/publicsuffix: Public Suffix List implementation
• gopkg.in/yaml.v3: YAML parsing library

WHOIS/RDAP server lists are sourced from:

• IANA
• IANA RDAP Bootstrap
• IANA RDAP Bootstrap (IPv4)
• IANA RDAP Bootstrap (IPv6)
• IANA RDAP Bootstrap (AS)

MIT License