Repository files navigation

Whois is an intelligent — pure Ruby — WHOIS client and parser.

This library was extracted fromRoboWhois andRoboDomain, and it's now in use atDNSimple. It has been performing queries in production since July 2009.

Whois is free software, but it requires a lot of coffee to write, test, and distribute it. You can support the development bydonating a coffee.

Any amount is greatly appreciated.

• Ability to lookup WHOIS record forIPv4, IPv6, TLDs, and ICANN new gTLDs
• Ability toparse WHOIS responses (via thewhois-parser library)
• Flexible and extensible interface (e.g. You can definecustom servers on the fly)
• Object oriented design, featuring 10 different design patterns
• Pure Ruby library, without any external dependency other than Ruby itself
• Successfully tested against different Ruby implementations, including Ruby and JRuby

Starting from version 4, WHOIS parser component is available in a separate repository calledwhois-parser, and released as a separate gem calledwhois-parser.

This repository contains the core whois library, that includes the WHOIS client, the server definitions and all the features required to perform WHOIS queries and obtain the WHOIS record.

• Ruby >= 3.0

For older versions of Ruby, see theCHANGELOG.

You can install the gem manually:

gem install whois

Or useBundler and define it as a dependency in yourGemfile:

gem'whois'

To use the WHOIS parser component you need to install thewhois-parser gem:

gem install whois-parser

gem'whois-parser'

Thewhois-parser gem already depends on thewhois gem. If you installwhois-parser,whois will be installed as well and it will also be automatically required when yourequire 'whois-parser'.

If you are upgrading to 4.0, see4.0-Upgrade.md.

This section covers only the essentials for getting started with the Whois library. Thedocumentation provides a more accurate explanation including tutorials, more examples and technical details about the client/server/record/parser architecture.

Whois provides the ability to get WHOIS information for TLD, domain names, IPv4 and IPv6 addresses. The client is smart enough to guess the best WHOIS server according to given query, send the request and return the response.

Check out the following examples:

# Domain WHOISwhois=Whois::Client.newwhois.lookup("google.com")# => #<Whois::Record># TLD WHOISwhois=Whois::Client.newwhois.lookup(".com")# => #<Whois::Record># IPv4 WHOISwhois=Whois::Client.newwhois.lookup("74.125.67.100")# => #<Whois::Record># IPv6 WHOISwhois=Whois::Client.newwhois.lookup("2001:db8::1428:57ab")# => #<Whois::Record>

The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.

whois=Whois::Client.newwhois.lookup("google.com")whois.lookup(".com")whois.lookup("74.125.67.100")whois.lookup("2001:db8::1428:57ab")whois.lookup("google.it")

If you just need a WHOIS response and you don't care about a full control of the WHOIS client, theWhois module provides an all-in-one method calledWhois.whois. This is the simplest way to send a WHOIS request.

Whois.whois("google.com")# => #<Whois::Record>

Did I mention you can even use blocks?

Whois::Client.newdo |w|w.lookup("google.com")w.lookup(".com")w.lookup("74.125.67.100")w.lookup("2001:db8::1428:57ab")w.lookup("google.it")end

Any WHOIS query returns aWhois::Record. This object looks like a String, but it's way more powerful.

Whois::Record encapsulates a WHOIS record and provides the ability to parse the WHOIS response programmatically, when thewhois-parser gem is installed and loaded.

require'whois-parser'record=Whois.whois("google.it")# => #<Whois::Record>parser=record.parser# => #<Whois::Parser>parser.available?# => falseparser.registered?# => trueparser.created_on# => Fri Dec 10 00:00:00 +0100 1999tech=parser.technical_contacts.first# => #<Whois::Record::Contact>tech.id# => "TS7016-ITNIC"tech.name# => "Technical Services"parser.nameservers.eachdo |nameserver|putsnameserverend

This feature is made possible by theWhois record parsers. Unfortunately, due to the lack of a global standard, each WHOIS server requires a specific parser. For this reason, the library doesn't support all existing WHOIS servers.

If you create a new parser, please consider releasing it to the public so that it can be included in a next version.

By default, each query run though the client has a timeout value of 5 seconds. If the execution exceeds the timeout limit, the client raises aTimeout::Error exception.

Of course, you can customize the timeout value setting a different value. If timeout isnil, the client will wait until the response is sent back from the server or the process is killed. Don't disable the timeout unless you really know what you are doing!

whois=Whois::Client.new(:timeout=>10)whois.timeout# => 10whois.timeout=5whois.timeout# => 5whois.lookup("google.com")

Whois was created and is maintained bySimone Carletti. Many improvements and bugfixes were contributed by theopen source community.

Direct questions and discussions toStack Overflow.

Pull requests are very welcome! Please include spec and/or feature coverage for every patch, and create a topic branch for every separate change you make.

Report issues or feature requests toGitHub Issues.

• Homepage
• RubyGems:whois andwhois-parser
• Issues:whois andwhois-parser
• Stack Overflow

Whois usesSemantic Versioning 2.0.0

Copyright (c) 2009-2024Simone Carletti. This is Free Software distributed under the MIT license.