whoisd

README

Whois Daemon

A quick and easy way to setup your own WHOIS server with Elasticsearch/MySQL storage

Whois Daemon complies with the requirements of ICANN

Whois Daemon represents a light server which provide fast way to produce whois information. The daemon based on Elasticsearch storage (Mysql storage still in development).

Install

This package is "go-gettable", just do:

go get github.com/takama/whoisd

Testing

whoisd -t -config=test/testconfig.conf -mapping=test/testmapping.json

Running

Start of whoisd:

sudo whoisd

or start as daemon

sudo whoisd install
sudo whoisd start

This will bring up whoisd listening on port 43 for client communication.

Usage

whoisd - Whois Daemon

Usage:
  whoisd install | remove | start | stop | status
  whoisd [ -t | --test ] [ -option | -option ... ]
  whoisd -h | --help
  whoisd -v | --version

Commands:
  install           Install as service (is only valid for Linux and Mac Os X)
  remove            Remove service
  start             Start service
  stop              Stop service
  status            Check service status

  -h --help         Show this screen
  -v --version      Show version
  -t --test         Test mode

Options:
  -config=<path>    Path to config file (used in /etc/whoisd/whoisd.conf)
  -mapping=<path>   Path to mapping file (used in /etc/whoisd/conf.d/mapping.json)
  -host=<host/IP>   Host name or IP address
  -port=<port>      Port number
  -work=<number>    Number of active workers (default 1000)
  -conn=<number>    Number of active connections (default 1000)
  -storage=<type>   Type of storage (Elasticsearch, Mysql or Dummy for testing)
  -shost=<host/IP>  Storage host name or IP address
  -sport=<port>     Storage port number
  -base=<name>      Storage index or database name
  -table=<name>     Storage type or table name

Config

The config file should be in /etc/whoisd/whoisd.conf. Of course possible to load config settings from any other place through -config option. If config file is absent, used predefined configuration below:

{
  "host": "0.0.0.0",
  "port": 43,
  "workers": 1000,
  "connections": 1000,
  "storage": {
    "storageType": "Dummy",
    "host": "localhost",
    "port": 9200,
    "indexBase": "whois",
    "typeTable": "domain"
  }
}

NOTE: Valid storage types: Elasticsearch, Mysql, Dummy. Dummy storage has two records for testing: "example.tld" and "google.com". You can test it:

whois -h localhost example.tld

or

whois -h localhost google.com

These fixtures placed in "storage" package directory.

Mapping

All required fields for whoisd must be defined in the mapping file. The mapping file represent all fields in your database as key names in the whoisd. The mapping file should be in /etc/whoisd/conf.d/mapping.json. It possible to load mapping file through -mapping option. The context of the mapping file is described below:

[
  {
    "TLDs": ["eu"],
    "Fields" : {
      "01": {
        "key": "Domain Name: ",
        "name": ["name"],
        "related": "name"
      },
      "02": {
        "key": "Registry Domain ID: ",
        "name": ["domainId"],
        "related": "name"
      },
      "03": {
        "key": "Registrar WHOIS Server: ",
        "value": ["whois.yourwhois.eu"]
      }

  },
  {
    "TLDs": ["com", "net"],
    "Fields" : {
      "01": {
        "key": "Domain Name: ",
        "name": ["name"],
        "related": "name"
      },
      "02": {
        "key": "Registry Domain ID: ",
        "name": ["domainId"],
        "related": "name"
      },
      "03": {
        "key": "Registrar WHOIS Server: ",
        "value": ["whois.yourwhois.eu"]
      }

  }
]

• "TLDs" - a list of TLDs which accepted by Whois Daemon for specified fields
• "Fields" - a list of fields from "01" to last number "nn" in ascending order
• "key" - a label for the field (preinstalled config file has keys according to ICANN requirements)
• "value" - use it if the field has constant value (not defined field from the database)
• "name" - a name of the field in a database, if the field has not constant value ("value" is not defined)
• "related" - a name of the field in a database through which a request for

[
  {

      "06": {
        "key": "Creation Date: ",
        "name": ["creationDate"],
        "format": "{date}",
        "related": "name"
      }

  }
]

• "format" - special instructions to indicate how to display field, the examples shown below
• "{date}" - used in the format to indicate that the field is a 'date' and need special formatting of the date RFС3339

[
  {

      "12": {
        "key": "Domain Status: ",
        "name": ["domainStatus"],
        "multiple": true,
        "related": "name"
      },

      "52": {
        "key": "Name Server: ",
        "name": ["name"],
        "multiple": true,
        "related": "nsgroupId",
        "relatedBy": "nsgroupId",
        "relatedTo": "nameserver"
      }

  }
]

• "multiple" - if this option is set to 'true', each value will be repeated in whois output with the same label like that:

Name Server: ns1.example.com
Name Server: ns2.example.com
Name Server: ns3.example.com

• "relatedBy" - a name of the field in a database through which related a request for
• "relatedTo" - a name of the table/type in a database through which made a relation

[
  {

      "13": {
        "key": "Registry Registrant ID: ",
        "name": ["handle"],
        "hide": true,
        "related": "ownerHandle",
        "relatedBy": "handle",
        "relatedTo": "customer"
      },

  }
]

• "hide" - if this option is set to 'true', a value of the field will not shown in whois output

[
  {

      "14": {
        "key": "Registrant Name: ",
        "name": ["name.fullName"],
        "related": "ownerHandle",
        "relatedBy": "handle",
        "relatedTo": "customer"
      },

      "40": {
        "key": "Tech Name: ",
        "name": ["name.firstName", "name.lastName"],
        "related": "techHandle",
        "relatedBy": "handle",
        "relatedTo": "customer"
      }

  }
]

• "name": ["name.fullName"] - use dot notation for embedded fields (MySQL storage not allowed)
• "name": ["name.firstName", "name.lastName"] - all values of the fields will be joined by default

[
  {

      "21": {
        "key": "Registrant Phone: ",
        "name": ["phone.countryCode", "phone.areaCode", "phone.subscriberNumber"],
        "format": "{string}.{string}{string}",
        "related": "ownerHandle",
        "relatedBy": "handle",
        "relatedTo": "customer"
      }

  }
]

• "format": "{string}.{string}{string}" - indicate that the fields ["phone.countryCode", "phone.areaCode", "phone.subscriberNumber"] need special formatting "{string}.{string}{string}" (they are not simple joined)
• {string} - represent one string field in format option

[
  {

      "55": {
        "key": "",
        "value": [""],
        "format": ">>> Last update of WHOIS database: {date} <<<"
      }
  }
]

• a example of formating where used undefined tag "{date}", because a name of the field has not present, "{date}" will be replaced by CURRENT date in RFC3339 format

TODO

• in memory storage
• Rest API
• update storage records by Rest API

Copyright (c) 2015 Igor Dolzhikov

MIT License