The dns-client Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The dns-client Reference Manual

This is the dns-client Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Apr 28 11:41:57 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

## About dns-client
This is a pure-lisp implementation of a DNS client. You can use this to resolve hostnames, reverse-lookup IP addresses, and fetch other kinds of DNS records.

## How To
The primary interface is ``query``, with shorthands for the most common operations in ``resolve`` and ``hostname``.

:: common lisp
(org.shirakumo.dns-client:query "google.com" :type :MX)
;; => ... "alt3.aspmx.l.google.com"

(org.shirakumo.dns-client:resolve "aspmx.l.google.com")
;; => "173.194.76.26"

(org.shirakumo.dns-client:hostname "173.194.76.26")
;; => "ws-in-f26.1e100.net"

(org.shirakumo.dns-client:resolve "ws-in-f26.1e100.net")
;; => "173.194.76.26"
::

Some common record types are translated into more readable structures automatically. Unsupported ones will have their data available octets. If you find you need support for a record that's not implemented yet, please "contribute a patch"(https://github.com/shinmera/dns-client/pull/new).


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 dns-client

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://shinmera.github.io/dns-client/

Source Control

(:git "https://github.com/shinmera/dns-client.git")

Bug Tracker

https://github.com/shinmera/dns-client/issues

License

zlib

Description

A client for the DNS protocol.

Version

1.0.0

Dependencies
Source

dns-client.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 dns-client.asd

Location

dns-client.asd

Systems

dns-client (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 dns-client/package.lisp

Parent

dns-client (system)

Location

package.lisp

Packages

org.shirakumo.dns-client


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 dns-client/toolkit.lisp

Dependency

package.lisp (file)

Parent

dns-client (system)

Location

toolkit.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 dns-client/record-types.lisp

Dependency

toolkit.lisp (file)

Parent

dns-client (system)

Location

record-types.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 dns-client/client.lisp

Dependency

record-types.lisp (file)

Parent

dns-client (system)

Location

client.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 dns-client/documentation.lisp

Dependency

client.lisp (file)

Parent

dns-client (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 org.shirakumo.dns-client

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Constants

Constant: dns-port

The port used for DNS queries.

Should be 53.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Constant: recv-buffer-length

The buffer size for received DNS packets.

Defaults to 65507, which should be more than enough for all DNS queries. Note that while the standard DNS packet size used to (and still is in some devices) limited to 512 bytes, this restriction no longer applies generally.

Package

org.shirakumo.dns-client

Source

client.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Special variables

Special Variable: *cloudflare-servers*

List of IP addresses to CloudFlare’s DNS servers.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *dns-servers*

List of IP addresses to query for DNS records.

By default this is a combination of the localhost address and a bunch of other publicly available DNS servers, in rough order of trustworthiness and speed.

You may bind or modify this variable to suit your preferences.

See *CLOUDFLARE-SERVERS*
See *DNSWATCH-SERVERS*
See *GOOGLE-SERVERS*
See *OPENDNS-SERVERS*
See *QUAD9-SERVERS*
See QUERY

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *dnswatch-servers*

List of IP addresses to DNSWatch’s DNS servers.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *google-servers*

List of IP addresses to Google’s DNS servers.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *opendns-servers*

List of IP addresses to OpenDNS’ DNS servers.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *quad9-servers*

List of IP addresses to Quad9’s DNS servers.

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Special Variable: *record-type-table*

Table associating standardised names to DNS record type IDs.

This is a list where each entry should be a list of two elements, the standardised name as a symbol, and the (unsigned-byte 16) ID.

You should not need to modify this. The table contains all standardised records types.

See RECORD-TYPE-ID
See ID-RECORD-TYPE

Package

org.shirakumo.dns-client

Source

record-types.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Macros

Macro: with-dns-error-handling &body BODY

Wraps a handler around BODY that performs useful defaults.

In particular, it will cause CONTINUE to be invoked on all error responses that are a failure on the server side, but still let the error propagate for all failures that indicate a bad query.

See DNS-SERVER-FAILURE

Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Functions

Function: hostname IP &rest ARGS &key TYPE DNS-SERVERS ATTEMPTS

Perform a reverse DNS query.

Returns three values, the first hostname that was found (if any), a list of all hostnames that were found, and whether the query was successful. If the last value is NIL, the first two values are NIL as well.

See QUERY

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: id-record-type ID

Returns the standardised record name for the given record type ID.

If the record type ID is not known, the ID itself is returned instead.

See *RECORD-TYPE-TABLE*

Package

org.shirakumo.dns-client

Source

record-types.lisp (file)

Function: query HOSTNAME &key TYPE DNS-SERVERS ATTEMPTS

Perform a DNS query for the given hostname.

TYPE should be a DNS class name or class ID that identifies the type of record you want to retrieve.

DNS-SERVERS should be a list of DNS servers to consult for your query. Each server in the list is asked ATTEMPTS number of times before skipping ahead to the next one.

Returns a PLIST of the resulting query, if successful.

The result contains the following keys:

:QUESTIONS — A list of QUERY structures.
:ANSWERS — A list of RECORD structures.
:AUTHORITIES — A list of RECORD structures.
:ADDITIONAL — A list of RECORD structures.
:ID — The ID identifying the query. :RECURSION-DESIRED — Whether recursion was asked for. :TRUNCATED-MESSAGE — Whether the message was truncated. :OPERATION — The operation that was carried out.
:REPLY-P — Whether this is a reply.
:RESPONSE-CODE — The response status code. :CHECKING-DISABLED — Whether checking was disabled. :AUTHENTICATED-DATA — Whether the data is authorative. :Z-RESERVED — Reserved flag.
:RECURSION-AVAILABLE — Whether the server allows recursion. :QUESTION-COUNT — How many QUESTION records there are. :ANSWER-COUNT — How many ANSWER records there are. :AUTHORITY-COUNT — How many AUTHORITY records there are. :ADDITIONAL-COUNT — How many ADDITIONAL records there are.

A query structure is a plist with the following keys:

:NAME — The hostname that was queried.
:TYPE — The record type that was queried.
:CLASS — The record class that was queried.

A record structure is a plist with the following keys:

:NAME — The hostname the result relates to.
:TYPE — The record type.
:CLASS — The record class.
:TTL — The time this record remains valid for, in minutes.
:LENGTH — The length of the payload in octets.
:DATA — A record type specific data payload.

The client will translate record types from their octet data into a more easily digestible format for some record types:

:A — An IPv4 address in string format.
:AAAA — An IPv6 address in string format.
:TXT :URI :CNAME :PTR
— A hostname.
:MX — A plist with the following keys:
:PRIORITY
:NAME
:SOA — A plist with the following keys:
:MNAME
:RNAME
:SERIAL
:REFRESH
:RETRY
:EXPIRE
:MINIMUM

If a server is queried and has sent a response, but the response contains a non-zero response code, a condition of type DNS-SERVER-FAILURE is signalled. During this time, the CONTINUE restart can be used to skip the server and attempt the next one,
or the ABORT restart can be used to simply return NIL from QUERY.

If no server succeeds, an error of type DNS-SERVERS-EXHAUSTED
is signalled.

See DNS-SERVER-FAILURE
See DNS-SERVERS-EXHAUSTED
See RESOLVE
See HOSTNAME

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: query-data HOSTNAME &rest ARGS &key TYPE DNS-SERVERS ATTEMPTS

Shorthand to return the data payloads from the answers of a query.

This returns a list of all :DATA fields of :ANSWERS records from the query result that match the requested record type.

See QUERY

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: record-type-id RECORD-TYPE &optional ERROR

Returns the record type ID for the given record name.

If ERROR is non-NIL, and the given record type does not exist, an error is signalled. Otherwise, NIL is returned for inexistent record types.

See *RECORD-TYPE-TABLE*

Package

org.shirakumo.dns-client

Source

record-types.lisp (file)

Function: resolve HOSTNAME &rest ARGS &key TYPE DNS-SERVERS ATTEMPTS

Resolves a hostname to its IP address.

This is a shorthand to fetch the A or AAAA records.

Returns three values, the first IP that was found (if any), a list of all IPs that were found, and whether the query was successful. If the last value is NIL, the first two values are NIL as well.

See QUERY

Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: response-code-name CODE

Returns a name for the response code if one is known.

Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Generic functions

Generic Function: dns-server CONDITION

Returns the DNS server that returned the failure.

See DNS-SERVER-FAILURE

Package

org.shirakumo.dns-client

Methods
Method: dns-server (CONDITION dns-server-failure)
Source

toolkit.lisp (file)

Generic Function: response-code CONDITION

Returns the response code of the condition.

See DNS-SERVER-FAILURE
See RESPONSE-CODE-NAME

Package

org.shirakumo.dns-client

Methods
Method: response-code (CONDITION dns-server-failure)
Source

toolkit.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.6 Conditions

Condition: dns-condition ()

Base type for all DNS conditions.

Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses
Condition: dns-server-failure ()

Error signalled when a DNS server replies with a bad response code.

See DNS-CONDITION
See DNS-SERVER
See RESPONSE-CODE
See QUERY

Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Direct superclasses
Direct methods
Direct slots
Slot: dns-server
Initargs

:dns-server

Readers

dns-server (generic function)

Slot: response-code
Initargs

:response-code

Readers

response-code (generic function)

Condition: dns-servers-exhausted ()

Error signalled when all DNS servers fail to provide a response.

See DNS-CONDITION

Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Direct superclasses

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: maybe-set (OCTETS OFFSET) &body CALLS
Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Macro: with-decoding (OCTETS START &optional POS) &body BODY
Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Macro: with-encoding (OCTETS START &optional POS) &body BODY
Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: build-query HOSTNAME TYPE &rest HEADER-ARGS
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-data OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-header OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-host OCTETS OFFSET START
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-host* STRING
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-query OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-record OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: decode-response SERVER OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: encode-header OCTETS OFFSET &key ID RECURSION-DESIRED TRUNCATED-MESSAGE AUTHORATIVE-ANSWER OPERATION REPLY-P RESPONSE-CODE CHECKING-DISABLED AUTHENTICATED-DATA Z-RESERVED RECURSION-AVAILABLE QUESTION-COUNT ANSWER-COUNT AUTHORITY-COUNT ADDITIONAL-COUNT
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: encode-host NAME OCTETS OFFSET
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: encode-query OCTETS OFFSET HOSTNAME &key TYPE CLASS
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Function: split ON STRING
Package

org.shirakumo.dns-client

Source

toolkit.lisp (file)

Function: try-server SERVER SEND SEND-LENGTH RECV RECV-LENGTH &key ATTEMPTS
Package

org.shirakumo.dns-client

Source

client.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: decode-record-payload TYPE OCTETS START END
Package

org.shirakumo.dns-client

Source

client.lisp (file)

Methods
Method: decode-record-payload (TYPE (eql soa)) OCTETS START END
Method: decode-record-payload (TYPE (eql mx)) OCTETS START END
Method: decode-record-payload (TYPE (eql ptr)) OCTETS START END
Method: decode-record-payload (TYPE (eql cname)) OCTETS START END
Method: decode-record-payload (TYPE (eql uri)) OCTETS START END
Method: decode-record-payload (TYPE (eql txt)) OCTETS START END
Method: decode-record-payload (TYPE (eql aaaa)) OCTETS START END
Method: decode-record-payload (TYPE (eql a)) OCTETS START END
Method: decode-record-payload TYPE OCTETS START END

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
dns-client.asd: The dns-client․asd file
dns-client/client.lisp: The dns-client/client․lisp file
dns-client/documentation.lisp: The dns-client/documentation․lisp file
dns-client/package.lisp: The dns-client/package․lisp file
dns-client/record-types.lisp: The dns-client/record-types․lisp file
dns-client/toolkit.lisp: The dns-client/toolkit․lisp file

F
File, Lisp, dns-client.asd: The dns-client․asd file
File, Lisp, dns-client/client.lisp: The dns-client/client․lisp file
File, Lisp, dns-client/documentation.lisp: The dns-client/documentation․lisp file
File, Lisp, dns-client/package.lisp: The dns-client/package․lisp file
File, Lisp, dns-client/record-types.lisp: The dns-client/record-types․lisp file
File, Lisp, dns-client/toolkit.lisp: The dns-client/toolkit․lisp file

L
Lisp File, dns-client.asd: The dns-client․asd file
Lisp File, dns-client/client.lisp: The dns-client/client․lisp file
Lisp File, dns-client/documentation.lisp: The dns-client/documentation․lisp file
Lisp File, dns-client/package.lisp: The dns-client/package․lisp file
Lisp File, dns-client/record-types.lisp: The dns-client/record-types․lisp file
Lisp File, dns-client/toolkit.lisp: The dns-client/toolkit․lisp file

Jump to:   D   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   D   E   F   G   H   I   M   Q   R   S   T   W  
Index Entry  Section

B
build-query: Internal functions

D
decode-data: Internal functions
decode-header: Internal functions
decode-host: Internal functions
decode-host*: Internal functions
decode-query: Internal functions
decode-record: Internal functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-record-payload: Internal generic functions
decode-response: Internal functions
dns-server: Exported generic functions
dns-server: Exported generic functions

E
encode-header: Internal functions
encode-host: Internal functions
encode-query: Internal functions

F
Function, build-query: Internal functions
Function, decode-data: Internal functions
Function, decode-header: Internal functions
Function, decode-host: Internal functions
Function, decode-host*: Internal functions
Function, decode-query: Internal functions
Function, decode-record: Internal functions
Function, decode-response: Internal functions
Function, encode-header: Internal functions
Function, encode-host: Internal functions
Function, encode-query: Internal functions
Function, hostname: Exported functions
Function, id-record-type: Exported functions
Function, query: Exported functions
Function, query-data: Exported functions
Function, record-type-id: Exported functions
Function, resolve: Exported functions
Function, response-code-name: Exported functions
Function, split: Internal functions
Function, try-server: Internal functions

G
Generic Function, decode-record-payload: Internal generic functions
Generic Function, dns-server: Exported generic functions
Generic Function, response-code: Exported generic functions

H
hostname: Exported functions

I
id-record-type: Exported functions

M
Macro, maybe-set: Internal macros
Macro, with-decoding: Internal macros
Macro, with-dns-error-handling: Exported macros
Macro, with-encoding: Internal macros
maybe-set: Internal macros
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, decode-record-payload: Internal generic functions
Method, dns-server: Exported generic functions
Method, response-code: Exported generic functions

Q
query: Exported functions
query-data: Exported functions

R
record-type-id: Exported functions
resolve: Exported functions
response-code: Exported generic functions
response-code: Exported generic functions
response-code-name: Exported functions

S
split: Internal functions

T
try-server: Internal functions

W
with-decoding: Internal macros
with-dns-error-handling: Exported macros
with-encoding: Internal macros

Jump to:   B   D   E   F   G   H   I   M   Q   R   S   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   D   R   S  
Index Entry  Section

*
*cloudflare-servers*: Exported special variables
*dns-servers*: Exported special variables
*dnswatch-servers*: Exported special variables
*google-servers*: Exported special variables
*opendns-servers*: Exported special variables
*quad9-servers*: Exported special variables
*record-type-table*: Exported special variables

C
Constant, dns-port: Exported constants
Constant, recv-buffer-length: Exported constants

D
dns-port: Exported constants
dns-server: Exported conditions

R
recv-buffer-length: Exported constants
response-code: Exported conditions

S
Slot, dns-server: Exported conditions
Slot, response-code: Exported conditions
Special Variable, *cloudflare-servers*: Exported special variables
Special Variable, *dns-servers*: Exported special variables
Special Variable, *dnswatch-servers*: Exported special variables
Special Variable, *google-servers*: Exported special variables
Special Variable, *opendns-servers*: Exported special variables
Special Variable, *quad9-servers*: Exported special variables
Special Variable, *record-type-table*: Exported special variables

Jump to:   *  
C   D   R   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   D   O   P   S  
Index Entry  Section

C
Condition, dns-condition: Exported conditions
Condition, dns-server-failure: Exported conditions
Condition, dns-servers-exhausted: Exported conditions

D
dns-client: The dns-client system
dns-condition: Exported conditions
dns-server-failure: Exported conditions
dns-servers-exhausted: Exported conditions

O
org.shirakumo.dns-client: The org․shirakumo․dns-client package

P
Package, org.shirakumo.dns-client: The org․shirakumo․dns-client package

S
System, dns-client: The dns-client system

Jump to:   C   D   O   P   S