Class | Net::DNS::Resolver |
In: |
lib/net/dns/resolver/timeouts.rb
lib/net/dns/resolver.rb |
Parent: | Object |
The Net::DNS::Resolver class implements a complete DNS resolver written in pure Ruby, without a single C line of code. It has all of the tipical properties of an evoluted resolver, and a bit of OO which comes from having used Ruby.
This project started as a porting of the Net::DNS Perl module, written by Martin Fuhr, but turned out (in the last months) to be an almost complete rewriting. Well, maybe some of the features of the Perl version are still missing, but guys, at least this is readable code!
The Following Environment variables can also be used to configure the resolver:
# Bourne Shell $ RES_NAMESERVERS="192.168.1.1 192.168.2.2 192.168.3.3" $ export RES_NAMESERVERS # C Shell % setenv RES_NAMESERVERS "192.168.1.1 192.168.2.2 192.168.3.3"
# Bourne Shell $ RES_SEARCHLIST="example.com sub1.example.com sub2.example.com" $ export RES_SEARCHLIST # C Shell % setenv RES_SEARCHLIST "example.com sub1.example.com sub2.example.com"
# Bourne Shell $ LOCALDOMAIN=example.com $ export LOCALDOMAIN # C Shell % setenv LOCALDOMAIN example.com
# Bourne Shell $ RES_OPTIONS="retrans:3 retry:2 debug" $ export RES_OPTIONS # C Shell % setenv RES_OPTIONS "retrans:3 retry:2 debug"
Defaults | = | { :config_file => "/etc/resolv.conf", :log_file => $stdout, :port => 53, :searchlist => [], :nameservers => [IPAddr.new("127.0.0.1")], :domain => "", :source_port => 0, :source_address => IPAddr.new("0.0.0.0"), :source_address_inet6 => IPAddr.new('::'), :retry_interval => 5, :retry_number => 4, :recursive => true, :defname => true, :dns_search => true, :use_tcp => false, :ignore_truncated => false, :packet_size => 512, :tcp_timeout => TcpTimeout.new(5), :udp_timeout => UdpTimeout.new(5), } | An hash with the defaults values of almost all the configuration parameters of a resolver object. See the description for each parameter to have an explanation of its usage. | |
C | = | Object.const_get(defined?(RbConfig) ? :RbConfig : :Config)::CONFIG |
"nameservers=" | -> | "nameserver=" |
'retry_number=' | -> | 'retry=' |
"dns_search=" | -> | "dnsrch=" |
Creates a new resolver object.
Argument config can either be empty or be an hash with some configuration parameters. To know what each parameter do, look at the description of each. Some example:
# Use the sistem defaults res = Net::DNS::Resolver.new # Specify a configuration file res = Net::DNS::Resolver.new(:config_file => '/my/dns.conf') # Set some option res = Net::DNS::Resolver.new(:nameservers => "172.16.1.1", :recursive => false, :retry => 10)
Net::DNS::Resolver uses a config file to read the usual values a resolver needs, such as nameserver list and domain names. On UNIX systems the defaults are read from the following files, in the order indicated:
The following keywords are recognized in resolver configuration files:
Files except for /etc/resolv.conf must be owned by the effective userid running the program or they won‘t be read. In addition, several environment variables can also contain configuration information; see Environment in the main description for Resolver class.
On Windows Systems, an attempt is made to determine the system defaults using the registry. This is still a work in progress; systems with many dynamically configured network interfaces may confuse Net::DNS.
You can include a configuration file of your own when creating a resolver object:
# Use my own configuration file my $res = Net::DNS::Resolver->new(config_file => '/my/dns.conf');
This is supported on both UNIX and Windows. Values pulled from a custom configuration file override the the system‘s defaults, but can still be overridden by the other arguments to Resolver::new.
Explicit arguments to Resolver::new override both the system‘s defaults and the values of the custom configuration file, if any.
The following arguments to Resolver::new are supported:
For more information on any of these options, please consult the method of the same name.
Part of the above documentation is taken from the one in the Net::DNS::Resolver Perl module.
Returns true if running on a Windows platform.
Note. This method doesn‘t rely on the RUBY_PLATFORM constant because the comparison will fail when running on JRuby. On JRuby RUBY_PLATFORM == ‘java’.
Quick resolver method. Bypass the configuration using the defaults.
Net::DNS::Resolver.start "www.google.com"
Performs a zone transfer for the zone passed as a parameter.
It is actually only a wrapper to a send with type set as Net::DNS::AXFR, since it is using the same infrastucture.
Set the flag defname in a boolean state. if defname is true, calls to Resolver#query will append the default domain to names that contain no dots. Example:
# Domain example.com res.defname = true res.query("machine1") #=> This will perform a query for machine1.example.com
Default is true.
Set the flag dns_search in a boolean state. If dns_search is true, when using the Resolver#search method will be applied the search list. Default is true.
Set the log level for the built-in logging facility.
The log level can be one of the following:
Note that if the global variable $DEBUG is set (like when the -d switch is used at the command line) the logger level is automatically set at DEGUB.
For further informations, see Logger documentation in the Ruby standard library.
This one permits to have a personal logger facility to handle resolver messages, instead of new built-in one, which is set up for a +$stdout+ (or +$stderr+) use.
If you want your own logging facility you can create a new instance of the Logger class:
log = Logger.new("/tmp/resolver.log","weekly",2*1024*1024) log.level = Logger::DEBUG log.progname = "ruby_resolver"
and then pass it to the resolver:
res.logger = log
Note that this will destroy the precedent logger.
Get the list of resolver nameservers, in a dotted decimal format-
res.nameservers #=> ["192.168.0.1","192.168.0.2"]
Set the list of resolver nameservers. arg can be a single ip address or an array of addresses.
res.nameservers = "192.168.0.1" res.nameservers = ["192.168.0.1","192.168.0.2"]
If you want you can specify the addresses as IPAddr instances.
ip = IPAddr.new("192.168.0.3") res.nameservers << ip #=> ["192.168.0.1","192.168.0.2","192.168.0.3"]
The default is 127.0.0.1 (localhost)
Get the port number to which the resolver sends queries.
puts "Sending queries to port #{res.port}"
Set the port number to which the resolver sends queries. This can be useful for testing a nameserver running on a non-standard port.
res.port = 10053
The default is port 53.
Performs a DNS query for the given name. Neither the searchlist nor the default domain will be appended.
The argument list can be either a Net::DNS::Packet object or a name string plus optional type and class, which if omitted default to A and IN.
Returns a Net::DNS::Packet object.
# Executes the query with a +Packet+ object send_packet = Net::DNS::Packet.new("host.example.com", Net::DNS::NS, Net::DNS::HS) packet = res.query(send_packet) # Executes the query with a host, type and cls packet = res.query("host.example.com") packet = res.query("host.example.com", Net::DNS::NS) packet = res.query("host.example.com", Net::DNS::NS, Net::DNS::HS)
If the name is an IP address (Ipv4 or IPv6), in the form of a string or a IPAddr object, then an appropriate PTR query will be performed:
ip = IPAddr.new("172.16.100.2") packet = res.query(ip) packet = res.query("172.16.100.2")
Use +packet.header.ancount+ or +packet.answer+ to find out if there were any records in the answer section.
Performs a DNS query for the given name; the search list is not applied. If the name doesn‘t contain any dots and defname is true then the default domain will be appended.
The record type and class can be omitted; they default to A and IN. If the name looks like an IP address (IPv4 or IPv6), then an appropriate PTR query will be performed.
packet = res.query('mailhost') packet = res.query('mailhost.example.com') packet = res.query('example.com', Net::DNS::MX) packet = res.query('user.passwd.example.com', Net::DNS::TXT, Net::DNS::HS)
If the name is an IP address (Ipv4 or IPv6), in the form of a string or a IPAddr object, then an appropriate PTR query will be performed:
ip = IPAddr.new("172.16.100.2") packet = res.query(ip) packet = res.query("192.168.10.254")
Returns a Net::DNS::Packet object. If you need to examine the response packet whether it contains any answers or not, use the Resolver#query method instead.
Sets whether or not the resolver should perform recursive queries. Default is true.
res.recursive = false # perform non-recursive query
This method will return true if the resolver is configured to perform recursive queries.
print "The resolver will perform a " print res.recursive? ? "" : "not " puts "recursive query"
The number of times the resolver will try a query.
puts "Will try a max of #{res.retry_number} queries"
Performs a DNS query for the given name, applying the searchlist if appropriate. The search algorithm is as follows:
The record type and class can be omitted; they default to A and IN.
packet = res.search('mailhost') packet = res.search('mailhost.example.com') packet = res.search('example.com', Net::DNS::MX) packet = res.search('user.passwd.example.com', Net::DNS::TXT, Net::DNS::HS)
If the name is an IP address (Ipv4 or IPv6), in the form of a string or a IPAddr object, then an appropriate PTR query will be performed:
ip = IPAddr.new("172.16.100.2") packet = res.search(ip) packet = res.search("192.168.10.254")
Returns a Net::DNS::Packet object. If you need to examine the response packet whether it contains any answers or not, use the Resolver#query method instead.
Get the resolver search list, returned as an array of entries.
res.searchlist #=> ["example.com","a.example.com","b.example.com"]
Set the resolver searchlist. arg can be a single string or an array of strings.
res.searchstring = "example.com" res.searchstring = ["example.com","a.example.com","b.example.com"]
Note that you can also append a new name to the searchlist.
res.searchlist << "c.example.com" res.searchlist #=> ["example.com","a.example.com","b.example.com","c.example.com"]
The default is an empty array.
Get the local address from which the resolver sends queries
puts "Sending queries using source address #{res.source_address}"
Set the local source address from which the resolver sends its queries.
res.source_address = "172.16.100.1" res.source_address = IPAddr.new("172.16.100.1")
You can specify arg as either a string containing the ip address or an instance of IPAddr class.
Normally this can be used to force queries out a specific interface on a multi-homed host. In this case, you should of course need to know the addresses of the interfaces.
Another way to use this option is for some kind of spoofing attacks towards weak nameservers, to probe the security of your network. This includes specifing ranged attacks such as DoS and others. For a paper on DNS security, checks www.marcoceresa.com/security/
Note that if you want to set a non-binded source address you need root priviledges, as raw sockets will be used to generate packets. The class will then generate an exception if you‘re not root.
The default is 0.0.0.0, meaning any local address (chosen on routing needs).
Get the value of the source port number.
puts "Sending queries using port #{res.source_port}"
Set the local source port from which the resolver sends its queries.
res.source_port = 40000
Note that if you want to set a port you need root priviledges, as raw sockets will be used to generate packets. The class will then generate the exception ResolverPermissionError if you‘re not root.
The default is 0, which means that the port will be chosen by the underlaying layers.
Return a string representing the resolver state, suitable for printing on the screen.
puts "Resolver state:" puts res.state
Return an object representing the value of the stored TCP timeout the resolver will use in is queries. This object is an instance of the class TcpTimeout, and two methods are available for printing informations: TcpTimeout#to_s and TcpTimeout#pretty_to_s.
Here‘s some example:
puts "Timeout of #{res.tcp_timeout} seconds" # implicit to_s #=> Timeout of 150 seconds puts "You set a timeout of " + res.tcp_timeout.pretty_to_s #=> You set a timeout of 2 minutes and 30 seconds
If the timeout is infinite, a string "infinite" will be returned.
Set the value of TCP timeout for resolver queries that will be performed using TCP. A value of 0 means that the timeout will be infinite. The value is stored internally as a TcpTimeout object, see the description for Resolver#tcp_timeout
Default is 5 seconds.
Return an object representing the value of the stored UDP timeout the resolver will use in is queries. This object is an instance of the class UdpTimeout, and two methods are available for printing information: UdpTimeout#to_s and UdpTimeout#pretty_to_s.
Here‘s some example:
puts "Timeout of #{res.udp_timeout} seconds" # implicit to_s #=> Timeout of 150 seconds puts "You set a timeout of " + res.udp_timeout.pretty_to_s #=> You set a timeout of 2 minutes and 30 seconds
If the timeout is zero, a string "not defined" will be returned.
Set the value of UDP timeout for resolver queries that will be performed using UDP. A value of 0 means that the timeout will not be used, and the resolver will use only retry_number and retry_interval parameters.
Default is 5 seconds.
The value is stored internally as a UdpTimeout object, see the description for Resolver#udp_timeout.