kilabit.info
| AmA | Build | Email | GitHub | Mastodon | Projects | SourceHut

NAME

resolver - command line interface (CLI) for DNS and rescached server.

SYNOPSIS

resolver [-insecure] [-ns=<dns-URL>] [-server=<rescached-URL>] <command> [args...]

DESCRIPTION

resolver is a tool to resolve hostname to IP address or to query services on hostname by type (MX, SOA, TXT, etc.) using standard DNS protocol with UDP, DNS over TLS (DoT), or DNS over HTTPS (DoH).

It is also provide CLI to the rescached server to manage environment, block.d, hosts.d, and zone.d; as in the web user interface.

OPTIONS

The following options affect the commands operation.

-insecure

Ignore invalid server certificate when querying DoT, DoH, or rescached server. This option only affect the query command.

-ns=<dns-URL>

This option define the parent DNS server where the resolver send the query. This option only affect the query command.

The nameserver is defined in the following format,

("udp"/"tcp"/"https") "://" (domain / ip-address) [":" port]

Examples,

Default to one of "nameserver" in /etc/resolv.conf.

-server=<rescached-URL>

Set the rescached HTTP server where commands, except query, will be send. The rescached-URL use HTTP scheme:

("http" / "https") "://" (domain / ip-address) [":" port]

Default to https://127.0.0.1:5380 if its empty.

COMMANDS

GENERAL

help

Print the general usage.

version

Print the program version.

QUERY

query <domain / ip-address> [type] [class]

Query the domain or IP address with optional type and/or class.

Unless the option "-ns" is given, the query command will use the nameserver defined in the system resolv.conf file.

The "type" parameter define DNS record type to be queried. List of valid types,

  • A (1) - a host Address (default)

  • NS (2) - an authoritative Name Server

  • CNAME (5) - the Canonical NAME for an alias

  • SOA (6) - marks the Start of a zone of Authority

  • MB (7) - a MailBox domain name

  • MG (8) - a Mail Group member

  • MR (9) - a Mail Rename domain name

  • NULL (10) - a null resource record

  • WKS (11) - a Well Known Service description

  • PTR (12) - a domain name PoinTeR

  • HINFO (13) - Host INFOrmation

  • MINFO (14) - mailbox or mail list information

  • MX (15) - Mail Exchange

  • TXT (16) - TeXT strings

  • AAAA (28) - a host address in IPv6

  • SRV (33) - a SerViCe record

The "class" parameter is optional, its either IN (default), CS, or HS.

MANAGING BLOCK.D

block.d

List all block.d hosts file.

block.d disable <name>

Disable specific hosts on block.d.

block.d enable <name>

Enable specific hosts on block.d.

block.d update <name>

Fetch the latest hosts file from remote block.d URL defined by its name. On success, the hosts file will be updated and the server will be restarted.

MANAGING CACHES

caches

Fetch and print all caches from rescached server.

caches search <string>

Search the domain name in rescached caches. This command can also be used to inspect each DNS message on the caches.

caches remove <string>

Remove the domain name from rescached caches. If the parameter is "all", it will remove all caches.

MANAGING ENVIRONMENT

env

Fetch the current server environment and print it as JSON format to stdout.

env update <path-to-file / "-">

Update the server environment from JSON formatted file. If the argument is "-", the new environment is read from stdin. If the environment is valid, the server will be restarted.

MANAGING HOSTS.D

hosts.d create <name>

Create new hosts file inside the hosts.d directory with specific file name.

hosts.d delete <name>

Delete hosts file inside the hosts.d directory by file name.

hosts.d get <name>

Get the content of hosts file inside the hosts.d directory by file name.

MANAGING RECORD IN HOSTS.D

hosts.d rr add <name> <domain> <value>

Insert a new record and save it to the hosts file identified by "name". If the domain name already exists, the new record will be appended instead of replaced.

hosts.d rr delete <name> <domain>

Delete record from hosts file "name" by domain name.

MANAGING ZONE.D

zone.d

Fetch and print all zones in the server, including their SOA.

zone.d create <name>

Create new zone file inside the zone.d directory.

zone.d delete <name>

Delete zone file inside the zone.d directory.

MANAGING RECORD IN ZONE.D

zone.d rr get <zone>

Get and print all records in the zone.

zone.d rr add <zone> <"@" | subdomain> <ttl> <type> <class> <value> …​

Add new record into the zone file.

The domain name can be set to origin using "@" or empty string, subdomain (without ending with "."), or fully qualified domain name (end with ".").

If ttl is set to 0, it will default to 604800 (7 days).

List of valid type are A, NS, CNAME, PTR, MX, TXT, and AAAA.

List of valid class are IN, CS, HS.

The value parameter can be more than one, for example, the MX record we pass two parameters:

<pref> <exchange>

See the example below for more information.

zone.d rr delete <zone> <"@" | subdomain> <type> <class> <value>

Delete record from zone by its subdomain, type, class, and value.

EXIT STATUS

Upon exit and success resolver will return 0, or 1 otherwise.

EXAMPLES

QUERY

Query the IPv4 address for kilabit.info,

$ resolver query kilabit.info

Query the mail exchange (MX) for domain kilabit.info,

$ resolver query kilabit.info MX

Query the IPv4 address for kilabit.info using 127.0.0.1 at port 53 as name server,

$ resolver -ns=udp://127.0.0.1:53 query kilabit.info

Query the IPv4 address of domain name "kilabit.info" using DNS over TLS at name server 194.233.68.184,

$ resolver -insecure -ns=https://194.233.68.184 query kilabit.info

Query the IPv4 records of domain name "kilabit.info" using DNS over HTTPS on name server kilabit.info,

$ resolver -ns=https://kilabit.info/dns-query query kilabit.info

Inspect the rescached’s caches on server at http://127.0.0.1:5380,

$ resolver -server=http://127.0.0.1:5380 caches

MANAGING CACHES

Search caches that contains "bit" on the domain name,

$ resolver caches search bit

Remove caches that contains domain name "kilabit.info",

$ resolver caches remove kilabit.info

Remove all caches in the server,

$ resolver caches remove all

MANAGING ENVIRONMENT

Fetch and print current server environment,

$ resolver env

Update the server environment from JSON file in /tmp/env.json,

$ resolver env update /tmp/env.json

Update the server environment by reading JSON from standard input,

$ cat /tmp/env.json | resolver env update -

MANAGING HOSTS.D

Create new hosts file named "myhosts" inside the hosts.d directory,

$ resolver hosts.d create myhosts
OK

Delete hosts file named "myhosts" inside the hosts.d directory,

$ resolver hosts.d delete myhosts
OK

Get the content of hosts file named "myhosts" inside the hosts.d directory,

$ resolver hosts.d get myhosts
[
  {
    "Value": "127.0.0.1",
    "Name": "localhost",
    "Type": 1,
    "Class": 1,
    "TTL": 604800
  },
  {
    "Value": "::1",
    "Name": "localhost",
    "Type": 28,
    "Class": 1,
    "TTL": 604800
  }
]

MANAGING RECORD IN HOSTS.D

Add new record "127.0.0.1 my.hosts" to hosts file named "hosts",

$ resolver hosts.d rr add hosts my.hosts 127.0.0.1
{
  "Value": "127.0.0.1",
  "Name": "my.hosts",
  "Type": 1,
  "Class": 1,
  "TTL": 604800
}

Delete record "my.hosts" from hosts file "hosts",

$ resolver hosts.d rr delete hosts my.hosts
{
  "Value": "127.0.0.1",
  "Name": "my.hosts",
  "Type": 1,
  "Class": 1,
  "TTL": 604800
}

MANAGING ZONE.D

Print all zone in the server,

$ resolver zone.d
my.zone
  SOA: {MName:my.zone RName: Serial:0 Refresh:0 Retry:0 Expire:0 Minimum:0}

MANAGING RECORD IN ZONE.D

Assume that we have create zone "my.zone".

Get all records in the zone "my.zone",

$ resolver zone.d rr get my.zone
my.zone
  604800 MX IN map[Exchange:mail.my.zone Preference:10]
  604800  A IN 127.0.0.2
  604800  A IN 127.0.0.3
www.my.zone
  604800  A IN 192.168.1.2

Add IPv4 address "127.0.0.1" for domain my.zone,

$ resolver zone.d rr add my.zone @ 0 A IN 127.0.0.1

or

$ resolver zone.d rr add my.zone "" 0 A IN 127.0.0.1
{
  "Value": "127.0.0.1",
  "Name": "my.zone",
  "Type": 1,
  "Class": 1,
  "TTL": 604800
}

and to delete the above record,

$ resolver zone.d rr delete my.zone @ A IN 127.0.0.1
OK

Add subdomain "www" with IPv4 address "192.168.1.2" to zone "my.zone",

$ resolver zone.d rr add my.zone www 0 A IN 192.168.1.2
{
  "Value": "192.168.1.2",
  "Name": "www.my.zone",
  "Type": 1,
  "Class": 1,
  "TTL": 604800
}

and to delete the above record,

$ resolver zone.d rr delete my.zone www A IN 192.168.1.2
OK

AUTHOR

This software is developed by M. Shulhan (ms@kilabit.info).

LICENSE

Copyright 2018, M. Shulhan (ms@kilabit.info). All rights reserved.

Use of this source code is governed by a GPL 3.0 license that can be found in the COPYING file.

Source code repository: https://git.sr.ht/~shulhan/rescached

SEE ALSO

rescached(1), rescached.cfg(5)

Copyright 2007-2025, Shulhan <ms@kilabit.info>. All rights reserved.
Powered by ciigo