From 416ef5e2bf59bb2e45066a1d5d91ac677c0f48e5 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 10 Dec 2014 03:05:47 +0000 Subject: Initial commit --- doc/getaddrinfo.html | 94 ++++++++++ doc/index.html | 175 ++++++++++++++++++ doc/libresolv.html | 140 +++++++++++++++ doc/libs6dns/index.html | 104 +++++++++++ doc/libs6dns/s6dns-domain.html | 137 ++++++++++++++ doc/libs6dns/s6dns-engine.html | 255 ++++++++++++++++++++++++++ doc/libs6dns/s6dns-fmt.html | 92 ++++++++++ doc/libs6dns/s6dns-ip46.html | 69 +++++++ doc/libs6dns/s6dns-message.html | 261 +++++++++++++++++++++++++++ doc/libs6dns/s6dns-rci.html | 109 +++++++++++ doc/libs6dns/s6dns-resolve.html | 387 ++++++++++++++++++++++++++++++++++++++++ doc/s6-dnsip4-filter.html | 111 ++++++++++++ doc/s6-dnsip4.html | 63 +++++++ doc/s6-dnsip6-filter.html | 99 ++++++++++ doc/s6-dnsip6.html | 73 ++++++++ doc/s6-dnsmx.html | 64 +++++++ doc/s6-dnsname-filter.html | 103 +++++++++++ doc/s6-dnsname.html | 72 ++++++++ doc/s6-dnsns.html | 63 +++++++ doc/s6-dnsq.html | 82 +++++++++ doc/s6-dnsqr.html | 80 +++++++++ doc/s6-dnsqualify.html | 41 +++++ doc/s6-dnssoa.html | 65 +++++++ doc/s6-dnssrv.html | 65 +++++++ doc/s6-dnstxt.html | 77 ++++++++ doc/s6-randomip.html | 57 ++++++ doc/skadns/index.html | 262 +++++++++++++++++++++++++++ doc/skadns/skadnsd.html | 120 +++++++++++++ doc/upgrade.html | 32 ++++ 29 files changed, 3352 insertions(+) create mode 100644 doc/getaddrinfo.html create mode 100644 doc/index.html create mode 100644 doc/libresolv.html create mode 100644 doc/libs6dns/index.html create mode 100644 doc/libs6dns/s6dns-domain.html create mode 100644 doc/libs6dns/s6dns-engine.html create mode 100644 doc/libs6dns/s6dns-fmt.html create mode 100644 doc/libs6dns/s6dns-ip46.html create mode 100644 doc/libs6dns/s6dns-message.html create mode 100644 doc/libs6dns/s6dns-rci.html create mode 100644 doc/libs6dns/s6dns-resolve.html create mode 100644 doc/s6-dnsip4-filter.html create mode 100644 doc/s6-dnsip4.html create mode 100644 doc/s6-dnsip6-filter.html create mode 100644 doc/s6-dnsip6.html create mode 100644 doc/s6-dnsmx.html create mode 100644 doc/s6-dnsname-filter.html create mode 100644 doc/s6-dnsname.html create mode 100644 doc/s6-dnsns.html create mode 100644 doc/s6-dnsq.html create mode 100644 doc/s6-dnsqr.html create mode 100644 doc/s6-dnsqualify.html create mode 100644 doc/s6-dnssoa.html create mode 100644 doc/s6-dnssrv.html create mode 100644 doc/s6-dnstxt.html create mode 100644 doc/s6-randomip.html create mode 100644 doc/skadns/index.html create mode 100644 doc/skadns/skadnsd.html create mode 100644 doc/upgrade.html (limited to 'doc') diff --git a/doc/getaddrinfo.html b/doc/getaddrinfo.html new file mode 100644 index 0000000..da0469c --- /dev/null +++ b/doc/getaddrinfo.html @@ -0,0 +1,94 @@ + + + + + s6-dns: the problem with getaddrinfo() + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The problem with getaddrinfo()

+ +

+ The standard C library provides an API to perform name +resolution: +getaddrinfo(), +formerly gethostbyname(). However, for DNS resolution as well as +implementation in the libc, this interface is very impractical, to the point of +being unusable. Here are a few reasons why. +

+ +

getaddrinfo() performs NSS resolution, not DNS resolution.

+ +

+ I explained this point in a message to the +Busybox mailing-list. You can +read +the post here. +(There is a mistake in that post about /etc/nsswitch.conf and +/etc/host.conf syntax; the following two messages in the thread +correct that mistake.) +

+ +

+ TLDR: depending on the machine configuration, it is possible that +getaddrinfo() will not use DNS at all. +

+ +

It is unboundedly synchronous.

+ +

+ DNS resolution performs network I/O, which can take a non-negligible +amount of time. getaddrinfo() is a blocking call and there is +no way to specify a timeout to make it return early, so it may block +indefinitely. This is bad design. +

+ +

+ Also, network operations being asynchronous by nature, even a +synchronous API should provide a way to perform several queries at +once and return when one of them, or all of them, get an answer. +getaddrinfo() does not even offer that. +

+ +

It focuses on the wrong details.

+ +

+ Because it's generic, getaddrinfo() is cumbersome to use. + The data structures are impractical, requiring the user to fill in +information that is irrelevant to DNS resolution. The details of the +network transport protocols are of no interest to the user who just +wants answers to his DNS queries! +

+ +

+ But at the same time, getaddrinfo() does not allow the +user to provide the details he wants or refine his search. It's a very +basic and monolithic entry point, with no DNS-specific knobs. For +instance, only A and AAAA queries are supported, which is clearly +insufficient. +

+ +

Conclusion

+ +

+getaddrinfo() is a toy interface. For any half-serious DNS work, +another API must be used. +

+ +

+ Most people who need a real DNS client library use BIND's libresolv. +This page explains what is wrong with it, +and what s6-dns tries to do better. +

+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..5263664 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,175 @@ + + + + + s6-dns - a complete DNS client suite + + + + + + +

+Software
+skarnet.org +

+ +

s6-dns

+ +

What is it ?

+ +

+ s6-dns is a suite of DNS client programs and libraries for Unix +systems, as an alternative to the BIND, djbdns or other DNS clients. +

+ +

+ s6-dns may include its own series of DNS caches and servers at some +point in the future. +

+ +
+ + + +
+ +

Installation

+ +

Requirements

+ + + +

Licensing

+ +

+ s6-dns is free software. It is available under the +ISC license. +

+ +

Download

+ + + +

Compilation

+ + + +

Upgrade notes

+ + + +

Reference

+ +

Commands

+ +

+ All these commands exit 111 if they encounter a temporary error or +hardware error, and +100 if they encounter a permanent error - such as a misuse. Short-lived +commands exit 0 on success. Other exit codes are documented in the +relevant page. +

+ +

Command-line DNS clients programs

+ + + +

Filtering tools

+ + + +

Command-line qualification

+ + + +

DNS analysis and debug tools

+ + + +

Miscellaneous utilities

+ + + + +

Libraries

+ +

Protocol implementation and synchronous resolution

+ + + +

Asynchronous resolution

+ + + +
+ + +

Related resources

+ + +

s6-dns discussion

+ + + +

Similar work

+ + + + + diff --git a/doc/libresolv.html b/doc/libresolv.html new file mode 100644 index 0000000..7a9fd31 --- /dev/null +++ b/doc/libresolv.html @@ -0,0 +1,140 @@ + + + + + s6-dns: the problem with libresolv + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The problem with libresolv

+ +

+ The BIND name server software comes with its own client library, +named libresolv. +

+ +

+ As can be expected from an ISC product, libresolv is not good software. +Here are a few reasons why. +

+ +

libresolv's security model is flawed.

+ +

+ The same people who wrote BIND wrote libresolv. That is the amount of +trust you can place in libresolv. Ten years ago, the security status +of libresolv looked like +this. I am not +confident that is has improved: bugs in the software may have been +fixed, but new ones will appear, and most importantly, the security +management policy at ISC is still the same: security holes will be +denied instead of acknowledged and worked upon. +

+ +

+ If you find a bug, and a fortiori a security hole, in +s6-dns, you can be sure it will be fixed promptly with apologies +from the author. skarnet.org doesn't do obfuscation, and never lets +politics get in the way of technical quality. +

+ +

libresolv is unboundedly synchronous.

+ +

+ You'd expect a real DNS client library to do better in this aspect +than getaddrinfo(), but no: libresolv's +function calls are still purely synchronous and may uncontrollably +block if the network is unresponsive. +

+ +

+ Additionally, libresolv only provides a synchronous +interface to clients. Despite the fundamentally asynchronous nature +of DNS, and the need to implement asynchronous primitives +internally, only blocking calls are made available in the API. +This forces users to stack yet another piece of software on top +of their dependencies if they need asynchronous DNS resolution. +

+ +

+ libs6dns provides several layers of asynchronous interfaces. +The user has access to +low-level packet sending +and receiving, to +synchronous +resolution of several queries at once, and to a +real high-level asynchronous DNS library. +

+ +

It is too big for what it does.

+ +

+ The libresolv-2.13.so binary file compiled for an i386 +Debian Linux system is roughly 71k bytes. The libs6dns.so.2.0 +file, for the same system, is roughly 41k bytes, while offering +more functionality. libresolv does not do any high-level answer +parsing, so the user still has to do some work after the libresolv +calls. s6-dns tries to be small and still provide the user comfortable +interfaces. +

+ +

The API is cumbersome to use.

+ +

+ Some examples of less-than-ideal interfaces for the users: +

+ + + +

+ There is a reason why system calls and local functions take +user-supplied buffers as arguments. They are relatively fast, it is +not too costly to call them again if the buffer is too small the +first time, and the result is consistent, i.e. after the first call, +the right buffer length is known. But functions making +network exchanges with variable-length results from one call to +another ? Those need heap-allocated storage. It is +good design to avoid using the heap whenever possible, but it is +not good design to waste network round-trips to save a malloc(). +

+ +

Conclusion

+ +

+ Like many other "standards", and C library interfaces in particular, +libresolv is at best a mediocre one, that people use because +there has been nothing better so far. +

+ +

+ s6-dns tries to be an alternative solution - not as ambitious, +but based on solid design principles and a reliable code base. +

+ + + diff --git a/doc/libs6dns/index.html b/doc/libs6dns/index.html new file mode 100644 index 0000000..db7ee35 --- /dev/null +++ b/doc/libs6dns/index.html @@ -0,0 +1,104 @@ + + + + + s6-dns: the s6dns library interface + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6dns library interface

+ +

General information

+ +

+ libs6dns is a DNS client library, designed for clarity +and simplicity - which translates into smallness of the code. +

+ +

+ A major focus of libs6dns is to avoid unnecessary use +of heap memory. Memory is only allocated in the heap to store +queries and response packets during a DNS resolution process, and +to store the final answers into a user-provided + +stralloc; all the other operations use stack memory, and perform +as few copies as possible. +

+ +

Compiling

+ + + +

Linking

+ + + +

Programming

+ +

+ The s6dns.h header is actually a concatenation of other headers: +the libs6dns is separated into several modules, each of them with its +own header. +

+ + + +

+ (User-level asynchronous resolution functions are provided in the +skadns library.) +

+ +

+ Two functional macros are actually directly declared in the s6dns.h +header: +

+ + + + + diff --git a/doc/libs6dns/s6dns-domain.html b/doc/libs6dns/s6dns-domain.html new file mode 100644 index 0000000..b1492c3 --- /dev/null +++ b/doc/libs6dns/s6dns-domain.html @@ -0,0 +1,137 @@ + + + + + s6-dns: the s6dns_domain library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_domain library interface

+ +

+ The following functions and structures are declared in the s6-dns/s6dns-domain.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_domain provides primitives to perform basic operations +on domain names. +

+ +

Data structures

+ +

+ A s6dns_domain_t is a structure that s6dns uses internally to +represent a domain name. It can be in string form (or +decoded form), which is close to the printable form seen +by users, or in packet form (or encoded form), which +is the format used in the DNS protocol. +

+ +

+ A s6dns_domain_t is a flat structure and can be declared +on the stack. +

+ +

Functions

+ +

+ int s6dns_domain_fromstring (s6dns_domain_t *d, char const *s, unsigned int len)
+Makes a (string form) domain from string s of length len, +and stores it into *d. Returns 1 if it succeeds, otherwise it +returns 0 and sets errno appropriately - most likely ENAMETOOLONG, i.e. +the name in s is not a well-formed domain name. +

+ +

+ unsigned int s6dns_domain_tostring (char *s, unsigned int max, s6dns_domain_t const *d)
+Writes into string s the domain contained in *d (in string +form). Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +

+ +

+ int s6dns_domain_noqualify (s6dns_domain_t *d)
+Makes sure that *d is fully qualified. This is done without using +qualification: a trailing dot is simply appended if the domain +doesn't already have one. Returns 1 if it succeeds, or 0 if it fails. +

+ +

+ unsigned int s6dns_domain_qualify (s6dns_domain_t *list, s6dns_domain_t const *d, char const *rules, unsigned int rulesnum)
+Performs qualification on domain *d according to the first +rulesnum rules stored in string rules. Stores the output +(at most rulesnum domains) into the array pointed to by list. +Returns 0 on failure, or the number of written domains if it succeeds. This +number can be lesser than rulesnum, for instance if *d is +already fully qualified.
+Valid rules and rulesnum can be obtained via functions +declared in s6dns-rci.h. +

+ +

+ int s6dns_domain_encode (s6dns_domain_t *d)
+Encodes domain *d from string form to packet form. Returns 1 +if it succeeds or 0 if it fails - for instance, *d is not a +valid string form (EINVAL). +

+ +

+ unsigned int s6dns_domain_encodelist (s6dns_domain_t *list, unsigned int n)
+Encodes n domains pointed to by list from string form to packet form, +stopping at the first failure. +Returns the number of successfully encoded domains, normally n. +

+ +

+ int s6dns_domain_decode (s6dns_domain_t *d)
+Decodes domain *d from packet form to string form. Returns 1 +if it succeeds or 0 if it fails - for instance, *d is not a +valid packet form (EPROTO). +

+ +

+ int s6dns_domain_fromstring_noqualify_encode (s6dns_domain_t *d, char const *s, unsigned int len)
+Higher-level function wrapping some of the above. Makes an encoded, fully qualified +(without resorting to qualification) domain from string s of +length len. Returns 1 if it succeeds and 0 if it fails. +

+ +

+ unsigned int s6dns_domain_fromstring_qualify_encode (s6dns_domain_t *list, char const *s, unsigned int len, char const *rules, unsigned int rulesnum)
+Another wrapping function. It makes a list of encoded, fully qualified domains, +from string s of length len using rulesnum qualification +rules in rules. It writes at most rulesnum domains into the array +pointed to by list and returns the number of written domains, or 0 on an +error. +

+ +

+ void s6dns_domain_arpafromip4 (s6dns_domain_t *d, char const *ip)
+Writes into d the in-addr.arpa. domain corresponding to IPv4 address +ip (4 bytes, in network byte order), in string form. +

+ +

+ void s6dns_domain_arpafromip6 (s6dns_domain_t *d, char const *ip, unsigned int mask)
+Writes into d the ip6.arpa. domain corresponding to the first +mask bits of IPv6 address ip (16 bytes, in network byte order), +in string form. +Only multiples of 4 count for mask, i.e. the output will be the same +if mask is (for instance) 125, 126, 127 or 128. +

+ + + diff --git a/doc/libs6dns/s6dns-engine.html b/doc/libs6dns/s6dns-engine.html new file mode 100644 index 0000000..f0f9573 --- /dev/null +++ b/doc/libs6dns/s6dns-engine.html @@ -0,0 +1,255 @@ + + + + + s6-dns: the s6dns_engine library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_engine library interface

+ +

+ The following functions are declared in the s6-dns/s6dns-engine.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_engine is the nitty-gritty of DNS query management. These +are the low-level asynchronous primitives sending DNS queries over the +network, and getting answers. +

+ +

+ s6dns_engine has been inspired by Dan J. Bernstein's +dns_transmit +library, but does not borrow any code from it. Unlike +dns_transmit, s6dns_engine does not assume that +network send operations are instant successes; s6dns_engine +descriptors can be selected for writing as well as for reading. +Also, if the underlying +skalibs has been compiled with IPv6 support, s6dns_engine +supports native IPv6 transport. +

+ +

+ The s6dns_engine functions are used in the implementation of the +s6dns_resolven_loop function - which is nothing more than a +simple event loop around the s6dns_engine primitives - and the +skadnsd daemon. Both pieces of code are +good examples of how to use s6dns_engine. +

+ +

+ However, unless you're implementing a DNS cache, you probably should +not call the +s6dns_engine functions directly: they are very low-level. If you +need synchronous resolution, use the +s6dns_resolve functions. If you need +asynchronous DNS operations, use the +skadns functions, which are +designed to provide a higher level interface to multiple asynchronous +DNS queries. +

+ +

Data structures

+ +

+ A s6dns_engine_t structure holds all the data necessary to +manage a DNS query (and response). It must be initialized to S6DNS_ENGINE_ZERO +when first declared, and recycled with s6dns_engine_recycle() +after each use. It contains a stralloc, so it must be freed with +s6dns_engine_free() before being discarded, to avoid memory leaks. +

+ +

Functions

+ +

s6dns_engine_t life cycle

+ +

+ int s6dns_engine_init (s6dns_engine_t *dt, s6dns_ip46list_t const *servers, uint32 options, char const *q, unsigned int qlen, uint16 qtype, struct taia const *deadline, struct taia const *stamp) +

+ +

+Initializes dt with query q of length qlen +and type qtype. If d is an +encoded s6dns_domain_t, then d.s and d.len +are appropriate candidates for arguments q and qlen +respectively. +

+ +

+options can be 0 or an OR'ed +combination of the following, defined in s6-dns/s6dns-constants.h: +

+ + + +

+servers must point to a list of IP addresses as defined in +s6-dns/s6dns-ip46.h. Such a list can be +obtained from the /etc/resolv.conf file via the +s6dns_rci_fill() call when performing a +recursive query, or it must be constructed from a list of relevant +NS addresses when performing an iterative query. +

+ +

+stamp must be an accurate enough timestamp. deadline +sets up a deadline for the query: if the query hasn't been +satisfactorily answered by deadline - no matter how many +round-trips to network servers the library performs internally - then +it will be considered failed, and a timeout will be reported. +

+ +

+The function returns 1 if all went well, and 0 if an error occurred. +It returns instantly; it does not perform any network operation, +it just prepares dt to send a query. The actual data sending +will take place on the next s6dns_engine_event() call. +

+ +

+ void s6dns_engine_recycle (s6dns_engine_t *dt) +

+ +

+Recycles dt, making it ready for another use. This function +does not deallocate the heap memory used by dt, so it's faster than +s6dns_engine_free() and does not cause heap fragmentation. +

+ +

+ void s6dns_engine_free (s6dns_engine_t *dt) +

+ +

+Frees the heap memory used by dt. Also makes dt +ready for another use. It's advised to only use this function when +certain that dt will not be reused. +

+ +

Before the iopause()

+ +

+ The descriptor to select on is available as the fd field in +the s6dns_engine_t structure. +dt→fd should be read every iteration, because it can +change between iterations even if no event or timeout is reported +for dt. +

+ +

+ void s6dns_engine_nextdeadline (s6dns_engine_t const *dt, struct taia *a) +

+ +

+If dt needs handling before the absolute date *a, +then *a is updated +so it contains the earlier date. This is useful to compute the next +deadline in an iopause() loop. +

+ +

+ int s6dns_engine_isreadable (s6dns_engine_t const *dt) +

+ +

+Returns nonzero iff dt→fd is to be selected for reading. +Should be called in every iteration. +

+ +

+ int s6dns_engine_iswritable (s6dns_engine_t const *dt) +

+ +

+Returns nonzero iff dt→fd is to be selected for writing. +Should be called in every iteration. +

+ +

After the iopause()

+ +

+ int s6dns_engine_timeout (s6dns_engine_t *dt, struct taia const *stamp) +

+ +

+This function should be called if your selecting function returned 0, which +means that an event timed out. +stamp should contain the current time. The function returns -1 if +an error occurred, 1 if dt actually timed out, and 0 if nothing +special happened to dt (and your iopause timeout was caused by +something else). If the return value is not 0, dt is automatically +recycled. +

+ +

+ int s6dns_engine_event (s6dns_engine_t *dt, struct taia const *stamp) +

+ +

+This function should be called if your selecting function returned a positive +number, which means that some event got triggered. +stamp should contain the current time. The function returns +-1 if an error occurred (and dt is automatically recycled). It +returns 0 if no answer has arrived yet, and 1 if an answer is available. +

+ +

+The s6dns_engine_timeout() and s6dns_engine_event() functions, +when returning -1, make use of the following error codes: +

+ + +

+ char *s6dns_engine_packet (s6dns_engine_t const *dt) +

+ +

+Points to the response packet received from the network, +if s6dns_engine_event() returned 1. +

+ +

+ unsigned int s6dns_engine_packetlen (s6dns_engine_t const *dt) +

+ +

+Gives the length of the response packet, +if s6dns_engine_event() returned 1. +

+ +

+ You should recycle or free dt after reading the response packet. +

+ + + diff --git a/doc/libs6dns/s6dns-fmt.html b/doc/libs6dns/s6dns-fmt.html new file mode 100644 index 0000000..a586846 --- /dev/null +++ b/doc/libs6dns/s6dns-fmt.html @@ -0,0 +1,92 @@ + + + + + s6-dns: the s6dns_fmt library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_fmt library interface

+ +

+ The following functions and structures are declared in the s6-dns/s6dns-fmt.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_fmt provides primitives to format RR contents into +printable strings. +

+ +

Functions

+ +

+ unsigned int s6dns_fmt_domain (char *s, unsigned int max, s6dns_domain_t const *d)
+Writes into string s the domain contained in *d (in string +form). Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_DOMAIN is a suitable number of bytes to preallocate s. +This function is actually an alias to s6dns_domain_tostring. +

+ +

+ unsigned int s6dns_fmt_domainlist (char *s, unsigned int max, s6dns_domain_t const *list, unsigned int n, char const *delin, unsigned int delimlen)
+Writes into string s the list of n domains (in string form) +pointed to by list. Between each domain (and not after the last one), +string delim of length delimlen is appended. +The function returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_DOMAINLIST(n) is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_hinfo (char *s, unsigned int max, s6dns_message_rr_hinfo_t const *p)
+Writes into string s the HINFO contained in *p: cpu, then os, +separated by a space. +Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_HINFO is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_mx (char *s, unsigned int max, s6dns_message_rr_mx_t const *p)
+Writes into string s the MX contained in *p: preference, then +exchanger name, separated by a space. +Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_MX is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_soa (char *s, unsigned int max, s6dns_message_rr_soa_t const *p)
+Writes into string s the SOA contained in *p: +mname, then rname, then serial number, refresh time, retry time, expiration time +and minimum time, separated by spaces. +Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_SOA is a suitable number of bytes to preallocate s. +

+ +

+ unsigned int s6dns_fmt_srv (char *s, unsigned int max, s6dns_message_rr_srv_t const *p)
+Writes into string s the SRV contained in *p: priority, +then weight, then port, then target, separated by spaces. +Returns the number of bytes written, or 0 in case of failure. If +the output would be more than max bytes, 0 ENAMETOOLONG is returned. +To avoid that, S6DNS_FMT_SRV is a suitable number of bytes to preallocate s. +

+ + + diff --git a/doc/libs6dns/s6dns-ip46.html b/doc/libs6dns/s6dns-ip46.html new file mode 100644 index 0000000..27cbe2c --- /dev/null +++ b/doc/libs6dns/s6dns-ip46.html @@ -0,0 +1,69 @@ + + + + + s6-dns: the s6dns_ip46 library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_ip46 library interface

+ +

+ The following functions are declared in the s6-dns/s6dns-ip46.h header, +and implemented as macros. +

+ +

General information

+ +

+ s6dns_ip46 is the transport abstraction layer. It allows +the functions declared in s6-dns/s6dns-engine.h +and s6-dns/s6dns-rci.h to be transport-agnostic, +i.e. to be able to work with both IPv4 and IPv6. +

+ +

+ If the underlying skalibs +has been compiled with + flag-noipv6, +or if it has detected at build time that the target host does not support +IPv6, then the s6dns-ip46 abstraction will be totally transparent and use +no resources at all. +

+ +

Data structures

+ +

+ A s6dns_ip46list_t structure holds a list of S6DNS_MAX_SERVERS (16) +IPv4 or IPv6 addresses. Such a mixed list can be constructed, for +instance, if the /etc/resolv.conf file contains both v4 and v6 +nameserver lines. +

+ +

Functions

+ +

+ If list is a s6dns_ip46list_t and i an integer +between 0 and DNS_MAX_SERVERS-1, then +

+ + + + + diff --git a/doc/libs6dns/s6dns-message.html b/doc/libs6dns/s6dns-message.html new file mode 100644 index 0000000..e06aa91 --- /dev/null +++ b/doc/libs6dns/s6dns-message.html @@ -0,0 +1,261 @@ + + + + + s6-dns: the s6dns_message library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_message library interface

+ +

+ The following functions are declared in the s6-dns/s6dns-message.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_message provides functions to read and parse DNS messages +sent by servers and caches and containing answers to queries. +

+ +

Data structures

+ +

+ A s6dns_message_header_t is a structure containing the header +of a received DNS packet, broken down for easy access to the bits. +

+ +

+ A s6dns_message_rr_t is a structure containing the information +about a resource record given by an answer packet - all of it, except the +value of the answer itself, which is rtype-specific and has to be decoded +by rtype-specific functions. +

+ +

+ A s6dns_message_rr_func_t is the type of such a function. The +prototype is
+ int f (s6dns_message_rr_t const *rr, char const *packet, unsigned int packetlen, unsigned int pos, unsigned int section, void *data)
+

+ + + +

+ Various structures designed to store specific resource record types are +also provided. The list includes: +

+ + + +

Functions

+ +

Header management

+ +

+ void s6dns_message_header_pack (char *s, s6dns_message_header_t const *h)
+Packs the header *h into the 12 bytes pointed to by s. +

+ +

+ void s6dns_message_header_unpack (char const *s, s6dns_message_header_t *h)
+Unpacks the 12 bytes pointed to by s into the structure *h. +

+ +

Low-level RR decoding

+ +

+ The following primitives are used in the implementation of +s6dns_message_rr_func_t-typed functions, to read and decode information +stored in a DNS packet. Their arguments are: +

+ +
    +
  1. A pointer to the structure where the information is going to be stored
    2. +
  2. A read-only pointer to the beginning of the DNS packet
    3. +
  3. The length of the DNS packet
    4. +
  4. A pointer to an integer containing the current position in the +DNS packet, i.e. where the information is going to be read. If the functions +succeed, they automatically update the position so information can be read +sequentially.
    5. +
+ +

+ int s6dns_message_get_string (s6dns_domain_t *d, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a character-string and stores it into *d. Returns 1 on success +and 0 on failure. Note that *d does not contain a domain, but the +s6dns_domain_t structure is adapted to store strings that do not +exceed 255 characters. d→s can be used to access the string, +and d→len its length. +

+ +

+ int s6dns_message_get_strings (char *s, unsigned int rdlength, char const *packet, unsigned int packetlen, unsigned int *pos
+This function takes an additional parameter rdlength. It reads a series of +character-strings and stores their concatenation into the string s, which +must be preallocated; it can never store more than rdlength bytes. It returns +-1 if it fails; on success, it returns the number of bytes written. The +rdlength parameter must be the length of the resource record containing +the series of character-strings. +

+ +

+ unsigned int s6dns_message_get_domain (s6dns_domain_t *d, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a domain and stores it, in string form, into *d. +Returns 1 on success and 0 on failure, and sets errno: +

+ + + +

+ int s6dns_message_get_hinfo (s6dns_message_rr_hinfo_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a HINFO RR and stores it into *p. Returns 1 on success or 0 +on failure. +

+ +

+ int s6dns_message_get_mx (s6dns_message_rr_mx_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a MX RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

+ int s6dns_message_get_soa (s6dns_message_rr_soa_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a SOA RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

+ int s6dns_message_get_srv (s6dns_message_rr_srv_t *p, char const *packet, unsigned int packetlen, unsigned int *pos)
+Reads a SRV RR and stores it into *p. Returns 1 on success or 0 on failure. +

+ +

High-level RR-specific parsing functions

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_strings
+Parses character-strings located in the answer section of the packet. The +data argument is interpreted as a pointer to a s6dns_mpag_t, +which is a structure defined in the s6-dns/s6dns-message.h header +and used to store multiple character-strings. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_domain
+Parses domains located in the answer section of the packet. The +data argument is interpreted as a pointer to a s6dns_dpag_t, +which is a structure defined in the s6-dns/s6dns-message.h header +and used to store multiple domains. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_a
+Parses A RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +stralloc, +and 4 bytes are appended to this stralloc for every IPv4 address found. +

+ + + s6dns_message_func_t s6dns_message_parse_answer_aaaa
+Parses AAAA RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +stralloc, +and 16 bytes are appended to this stralloc for every IPv6 address found. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_hinfo
+Parses HINFO RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_hinfo_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_mx
+Parses MX RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_mx_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_soa
+Parses SOA RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_soa_t structures. +

+ +

+ s6dns_message_func_t s6dns_message_parse_answer_srv
+Parses SRV RRs located in the answer section of the packet. The +data argument is interpreted as a pointer to a +genalloc +containing s6dns_message_rr_srv_t structures. +

+ +

High-level packet parsing

+ +

+ int s6dns_message_parse (s6dns_message_header_t *h, char const *packet, unsigned int packetlen, s6dns_message_rr_func_t *f, void *data)
+ This function parses the DNS packet packet of length packetlen. +It stores the packet header into *h. Then, for every RR in the answer, +authority or additional section of the packet, it calls f with the +relevant parameters. data is the extra pointer given to f to +store information. The function returns 1 if the parsing succeeds. Otherwise it +returns -1 if there is a local error unrelated to the packet, or 0 if no +appropriate answer can be decoded from the packet. errno then contains one +of the following values: +

+ + + + + diff --git a/doc/libs6dns/s6dns-rci.html b/doc/libs6dns/s6dns-rci.html new file mode 100644 index 0000000..1cf8a0e --- /dev/null +++ b/doc/libs6dns/s6dns-rci.html @@ -0,0 +1,109 @@ + + + + + s6-dns: the s6dns_rci library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_rci library interface

+ +

+ The following functions and structures are declared in the s6-dns/s6dns-rci.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_rci provides functions to get information from +the /etc/resolv.conf file. +

+ +

Data structures

+ +

+ A s6dns_rci_t is a structure storing information +provided by the /etc/resolv.conf file, i.e. +

+ + + +

+ Nameserver addresses are stored in a +s6dns_ip46list_t. Qualification rules are +stored in a stralloc +with an additional integer storing the number of rules. +

+ +

+ Most programs won't need more than one s6dns_rci_t, so +the library provides the global variable s6dns_rci_here, used +by default in simple resolution macros. +

+ +

Functions

+ +

+ int s6dns_rci_init (s6dns_rci_t *rci, char const *file)
+Extracts information from file, which must be in /etc/resolv.conf +format, and stores it into *rci. rci must be previously +initialized to the S6DNS_RCI_ZERO constant. The function returns 1 if +it succeeds, or 0 (and sets errno) if it fails. +

+ +

+ If the DNSCACHEIP environment variable is set, and contains a list of +IP addresses separated by commas, semicolons, spaces, tabs, newlines or +carriage returns, then this list overrides any nameserver information +from file. If the variable is empty, file will be used +as the source of the information. +

+ +

+ If the DNSQUALIFY environment variable is set, a list of domain suffixes, +separated by spaces, tabs, newlines or carriage returns, is read from it, +and overrides any qualification information from file. If the +variable is empty, it amounts to one rule saying "no qualification". +

+ +

+ s6dns_init() is an alias to +s6dns_rci_init(&s6dns_rci_here, "/etc/resolv.conf"). +

+ +

+ void s6dns_rci_free (s6dns_rci_t *rci)
+Frees the memory used by *rci. rci is then suitable to +be reused in a s6dns_rci_init call. +

+ +

+ s6dns_finish() calls s6dns_rci_free(&s6dns_rci_here). +

+ +

+ unsigned int s6dns_qualify (s6dns_domain_t *list, s6dns_domain_t const *d)
+Qualifies domain *d into the list of domains pointed to by list +according to the rules stored in s6dns_rci_here. Returns the number of +written domains (0 if it fails); this number cannot exceed +s6dns_rci_here.rulesnum. +

+ + + diff --git a/doc/libs6dns/s6dns-resolve.html b/doc/libs6dns/s6dns-resolve.html new file mode 100644 index 0000000..bbb3f57 --- /dev/null +++ b/doc/libs6dns/s6dns-resolve.html @@ -0,0 +1,387 @@ + + + + + s6-dns: the s6dns_resolve library interface + + + + + + +

+libs6dns
+s6-dns
+Software
+skarnet.org +

+ +

The s6dns_resolve library interface

+ +

+ The following functions are declared in the s6-dns/s6dns-resolve.h header, +and implemented in the libs6dns.a or libs6dns.so library. +

+ +

General information

+ +

+ s6dns_resolve provides functions and macros - mostly macros - +to perform high level synchronous DNS resolution. +

+ +

+ All the functions declared here make synchronous calls to the network, so +they can block for a non-negligible amount of time. To avoid unbounded +waiting times, they always take 2 arguments at the end, deadline +and stamp. deadline is the read-only address of a +struct taia +containing an absolute time which is the deadline for the function, and +stamp is the read-write address of a struct taia being +an accurate enough representation of the current absolute time. If +the function has not returned by *deadline, then it immediately +returns with a failure code and errno set to ETIMEDOUT. In every case, +*stamp is automatically updated so it always represents the +absolute time accurately enough. +

+ +

+ In a single-threaded program, the STAMP global variable can be used to +store the current time. Macros ending with _g use this variable +automatically so you don't have to provide the stamp argument +everytime. Additionally, several resolution functions make implicit use +of global variables such as: +

+ + + +

+ Reentrant, non-global-using functions are also provided, with the _r +suffix. In other words, if foobarfunc is a resolution function, +the following prototypes are generally provided, from the simplest to the +most complex: +

+ + + +

+ For each set of four functions, only one is documented here. +The other prototypes can be found in the s6-dns/s6dns-resolve.h file. +

+ +

+ Some errno codes reported by these functions do not have +exactly the system meaning given by +strerror(). +To get a user-friendly error message, use +s6dns_constants_error_str(errno) instead. The s6dns_constants_error_str +function is declared in the s6dns-constants.h header. +

+ +

Functions

+ +

Single query resolution

+ +

+ These functions are ordered from the lowest level to the highest level. +

+ +

Basic wrapper around s6dns_engine

+ +

+ int s6dns_resolve_loop_r_g (s6dns_engine_t *dt, struct taia const *deadline)
+Resolves the query stored in dt. +Returns 1 on success or 0 on failure. +

+ +

Generic resolution functions

+ +

+ int s6dns_resolve_core_g (s6dns_domain_t const *d, uint16 qtype, struct taia const *deadline)
+Resolves the query on domain *d (in packet form), of type qtype. +Returns 0 on failure, or 1 on success, in which case +s6dns_engine_here contains the answer. +

+ +

+ int s6dns_resolve_parse_g (s6dns_domain_t const *d, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Resolves the query on domain *d (in packet form), of type qtype, +then parses the answer with function f and stores the result into data. +Returns 1 if it succeeds, 0 if no data can be extracted from the answer, or -1 if an +error occurs. Sets errno in the last two cases. +

+ +

+ Note that the function can return 1 without appending anything to data. +This means that the servers confirmed that the domain exists, but f +has not been able to find any data relevant to the query in the answer. +This is very different from NXDOMAIN, which means that +the servers deny the actual existence of the domain, and which is reported +here as a return code of 0 with errno set to ENOENT. +

+ +

+ int s6dns_resolvenoq_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Performs a query of type qtype on name name of length len, +without qualifying it. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if no data can be extracted, +or -1 if an error occurs. Sets errno in the last two cases. +

+ +

+ int s6dns_resolveq_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, struct taia const *deadline)
+Performs a query of type qtype on name name of length len, +qualifying it first. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if none of the FQDNs can +get a positive answer, or -1 if an error occurs. Sets errno in the last two cases. +

+ +

+ int s6dns_resolve_g (char const *name, unsigned int len, uint16 qtype, s6dns_message_rr_func_t *f, void *data, int qualif, struct taia const *deadline)
+Performs a query of type qtype on name name of length len. +Qualifies name first if qualif is nonzero; else, does not +qualify it. Parses the answer with function f and stores the +result into data. Returns 1 if it succeeds, 0 if none of the FQDNs can +get a positive answer, or -1 if an error occurs. Sets errno in the last two cases. +

+ +

High-level type-specific functions

+ +

+ int s6dns_resolve_a_g (stralloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an A query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the IPs are +appended to the stralloc *ips, using 4 bytes per answer. +

+ +

+ int s6dns_resolve_aaaa_g (stralloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an AAAA query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the IPs are +appended to the stralloc *ips, using 16 bytes per answer. +

+ +

+ int s6dns_resolve_aaaaa_g (genalloc *ips, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs an AAAA query and an A query at the same time on name name +of length len, qualifying it first iff qualif is nonzero. +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or a positive number if it succeeds: 1 if IPv4 addresses +were found, 2 if IPv6 addresses were found, and 3 if both were found. +The IPs are appended to the genalloc *ips, which contains an array of +ip46_t, the skalibs structure used to store IPv4 and IPv6 addresses +indiscriminately. +

+ +

+ int s6dns_resolve_ptr_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a PTR query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name4_g (genalloc *ds, char const *ip, struct taia const *deadline)
+Performs a PTR query on the in-addr.arpa. name representing the IPv4 +address ip (4 network-order bytes). +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name6_g (genalloc *ds, char const *ip, struct taia const *deadline)
+Performs a PTR query on the ip6.arpa. name representing the IPv6 +address ip (16 network-order bytes). +Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_name46_g (genalloc *ds, ip46_t const *ip, struct taia const *deadline)
+Calls s6dns_resolve_name6_g() or s6dns_resolve_name4_g() +depending on which ip is an IPv6 or IPv4 address. +

+ +

+ int s6dns_resolve_ns_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a NS query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_cname_g (genalloc *ds, char const *name, unsigned int len, int qualif, struct taia const *deadline)
+Performs a CNAME query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *ds, which contains an array of s6dns_domain_t. +

+ +

+ int s6dns_resolve_hinfo_g (genalloc *hinfos, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an HINFO query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *hinfos, which contains an array of +s6dns_message_rr_hinfo_t. +

+ +

+ int s6dns_resolve_mx_g (genalloc *mxs, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an MX query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *mxs, which contains an array of +s6dns_message_rr_mx_t. +

+ +

+ int s6dns_resolve_soa_g (genalloc *soas, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an SOA query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *soas, which contains an array of +s6dns_message_rr_soa_t. +

+ +

+ int s6dns_resolve_srv_g (genalloc *srvs, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an SRV query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case the domains are +appended to the genalloc *srvs, which contains an array of +s6dns_message_rr_srv_t. +

+ +

+ int s6dns_resolve_txt_g (stralloc *sa, genalloc *offsets, char const *name, +unsigned int len, int qualif, struct taia const *deadline)
+ Performs an TXT query on name name of length len, qualifying it +iff qualif is nonzero. Returns -1 if an error occurs, or 0 if no answer +can be obtained from servers, or 1 if it succeeds, in which case: +

+ + + +

Parallel resolution

+ +

+ int s6dns_resolven_loop_g (s6dns_engine_t *dtl, unsigned int n, +unsigned int or, struct taia const *deadline)
+ Resolves the n queries stored in the array pointed to by dtl, +in parallel. If or is zero, it does not return before all answers +have arrived. If or is 1, it returns when an answer arrives, but does +not return if a query generates an error (unless all queries do so). If +or is 2, it returns when an answer arrives or an error occurs. +Other values of or are unspecified yet. + +

+ The return code is as follows: +

+ + + +

+ If or is 1, a return code of -1 with errno set to ENOENT +means that all the queries failed. +

+ +

+ After the function returns, the status field of each +s6dns_engine_t contains the error code relative to the query. +A status of 0 means that an answer has properly arrived; EAGAIN means +that the query is still pending (and the s6dns_engine_t has not been +recycled); ECONNABORTED means that the query has not been properly +initialized. Other codes report various network problems. +

+ +

+ int s6dns_resolven_parse_g (s6dns_resolve_t const *list, unsigned int n, +struct taia const *deadline)
+Performs n complete resolutions in parallel, parsing the results. +Returns 1 in case of success or 0 if a global error occurred. +

+ +

+list is a pointer to an array of n s6dns_resolve_t, +which is a structure containing at least the following fields: +

+ + + +

+ The s6dns_resolven_parse() function is a simple, convenient way to +perform several resolutions in parallel to avoid the waiting time +incurred by serial resolutions. However, it is still a synchronous +function, and cannot replace a real asynchronous DNS library: for +more complex parallel resolution needs, use the +skadns library. +

+ + + diff --git a/doc/s6-dnsip4-filter.html b/doc/s6-dnsip4-filter.html new file mode 100644 index 0000000..5433438 --- /dev/null +++ b/doc/s6-dnsip4-filter.html @@ -0,0 +1,111 @@ + + + + + s6-dns: the s6-dnsip4-filter program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsip4-filter program

+ +

+ s6-dnsip4-filter reads domain names on its standard input and +prints the corresponding IPv4 addresses on its standard output. +

+ +

Interface

+ +
+     s6-dnsip4-filter [ -l maxlines ] [ -c maxconn ] [ -t timeout ] [ -f normalfmt ] [ -e errorfmt ]
+
+ + + +

Options

+ + + +

Formatting rules

+ +

+ normalfmt and errorfmt are format strings, i.e. they tell the +program how a line must be printed. The following sequences are recognized: +

+ + + +

Example

+ +
+     s6-dnsns google.com | s6-dnsip4-filter -f "%d"
+
+ +

+ prints all the nameserver addresses for the google.com +domain. This is useful, for instance, to give the result as an +argument to s6-dnsq. +

+ +

Notes

+ +

+ s6-dnsip4-filter does not perform DNS resolutions itself. Instead, if forks +a skadnsd child and sends it queries, getting +the results asynchronously. The s6-dns filter programs have actually been +written as example uses of the skadns library. +

+ + + diff --git a/doc/s6-dnsip4.html b/doc/s6-dnsip4.html new file mode 100644 index 0000000..72f585b --- /dev/null +++ b/doc/s6-dnsip4.html @@ -0,0 +1,63 @@ + + + + + s6-dns: the s6-dnsip4 program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsip4 program

+ +

+ s6-dnsip4 finds the IPv4 addresses associated to a domain name. +

+ +

Interface

+ +
+     s6-dnsip4 [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-dnsip6-filter.html b/doc/s6-dnsip6-filter.html new file mode 100644 index 0000000..7cbad6b --- /dev/null +++ b/doc/s6-dnsip6-filter.html @@ -0,0 +1,99 @@ + + + + + s6-dns: the s6-dnsip6-filter program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsip6-filter program

+ +

+ s6-dnsip6-filter reads domain names on its standard input and +prints the corresponding IPv6 addresses on its standard output. +

+ +

Interface

+ +
+     s6-dnsip6-filter [ -l maxlines ] [ -c maxconn ] [ -t timeout ] [ -f normalfmt ] [ -e errorfmt ]
+
+ + + +

Options

+ + + +

Formatting rules

+ +

+ normalfmt and errorfmt are format strings, i.e. they tell the +program how a line must be printed. The following sequences are recognized: +

+ + + +

Notes

+ +

+ s6-dnsip6-filter does not perform DNS resolutions itself. Instead, if forks +a skadnsd child and sends it queries, getting +the results asynchronously. The s6-dns filter programs have actually been +written as example uses of the skadns library. +

+ + + diff --git a/doc/s6-dnsip6.html b/doc/s6-dnsip6.html new file mode 100644 index 0000000..d417011 --- /dev/null +++ b/doc/s6-dnsip6.html @@ -0,0 +1,73 @@ + + + + + s6-dns: the s6-dnsip6 program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsip6 program

+ +

+ s6-dnsip6 finds the IPv6 addresses associated to a domain name. +

+ +

Interface

+ +
+     s6-dnsip6 [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + +

Notes

+ +

+ Bear in mind that making AAAA queries is very different, and +totally independent, from using IPv6 transport for the DNS queries. +Even if the underlying skalibs has been compiled without IPv6 support, +or IPv6 DNS transport is unavailable for any reason, you can still perform +AAAA queries and s6-dnsip6 will answer correctly. +

+ + + diff --git a/doc/s6-dnsmx.html b/doc/s6-dnsmx.html new file mode 100644 index 0000000..1396aed --- /dev/null +++ b/doc/s6-dnsmx.html @@ -0,0 +1,64 @@ + + + + + s6-dns: the s6-dnsmx program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsmx program

+ +

+ s6-dnsmx finds the MX information associated to a domain name. +

+ +

Interface

+ +
+     s6-dnsmx [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-dnsname-filter.html b/doc/s6-dnsname-filter.html new file mode 100644 index 0000000..1554270 --- /dev/null +++ b/doc/s6-dnsname-filter.html @@ -0,0 +1,103 @@ + + + + + s6-dns: the s6-dnsname-filter program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsname-filter program

+ +

+ s6-dnsname-filter reads IP addresses on its standard input and +prints the corresponding domain names on its standard output. +

+ +

Interface

+ +
+     s6-dnsname-filter [ -4 ] [ -6 ] [ -l maxlines ] [ -c maxconn ] [ -t timeout ] [ -f normalfmt ] [ -e errorfmt ]
+
+ + + +

Options

+ + + +

Formatting rules

+ +

+ normalfmt and errorfmt are format strings, i.e. they tell the +program how a line must be printed. The following sequences are recognized: +

+ + + +

Notes

+ +

+ s6-dnsname-filter does not perform DNS resolutions itself. Instead, if forks +a skadnsd child and sends it queries, getting +the results asynchronously. The s6-dns filter programs have actually been +written as example uses of the skadns library. +

+ + + diff --git a/doc/s6-dnsname.html b/doc/s6-dnsname.html new file mode 100644 index 0000000..0c0c5b0 --- /dev/null +++ b/doc/s6-dnsname.html @@ -0,0 +1,72 @@ + + + + + s6-dns: the s6-dnsname program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsname program

+ +

+ s6-dnsname finds the name associated to an IPv4 or IPv6 address. +

+ +

Interface

+ +
+     s6-dnsname [ -4 | -6 ] [ -r ] [ -t timeout ] ip
+
+ + + +

Options

+ + + +

Notes

+ + + + + diff --git a/doc/s6-dnsns.html b/doc/s6-dnsns.html new file mode 100644 index 0000000..c15a7df --- /dev/null +++ b/doc/s6-dnsns.html @@ -0,0 +1,63 @@ + + + + + s6-dns: the s6-dnsns program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsns program

+ +

+ s6-dnsns finds the relevant nameservers providing data for a domain. +

+ +

Interface

+ +
+     s6-dnsns [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-dnsq.html b/doc/s6-dnsq.html new file mode 100644 index 0000000..9a22602 --- /dev/null +++ b/doc/s6-dnsq.html @@ -0,0 +1,82 @@ + + + + + s6-dns: the s6-dnsq program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsq program

+ +

+ s6-dnsq is an analysis and debug tool. It performs a non-recursive DNS query +to a given list of servers, +then prints the contents of the answer packet, and optionally debug +information during the resolution. +

+ +

Interface

+ +
+     s6-dnsq [ -1 | -2 ] [ -t timeout ] [ -D level ] qtype domain serverlist
+
+ + + +

Options

+ + + +

Notes

+ + + + + diff --git a/doc/s6-dnsqr.html b/doc/s6-dnsqr.html new file mode 100644 index 0000000..ce308bd --- /dev/null +++ b/doc/s6-dnsqr.html @@ -0,0 +1,80 @@ + + + + + s6-dns: the s6-dnsqr program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsqr program

+ +

+ s6-dnsqr is an analysis and debug tool. It performs a DNS resolution, +then prints the contents of the answer packet, and optionally debug +information during the resolution. +

+ +

Interface

+ +
+     s6-dnsqr [ -1 | -2 ] [ -t timeout ] [ -D level ] qtype domain
+
+ + + +

Options

+ + + +

Notes

+ + + + + diff --git a/doc/s6-dnsqualify.html b/doc/s6-dnsqualify.html new file mode 100644 index 0000000..f515be7 --- /dev/null +++ b/doc/s6-dnsqualify.html @@ -0,0 +1,41 @@ + + + + + s6-dns: the s6-dnsqualify program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnsqualify program

+ +

+ s6-dnsqualify qualifies a domain name. +

+ +

Interface

+ +
+     s6-dnsqualify domain
+
+ + + + + diff --git a/doc/s6-dnssoa.html b/doc/s6-dnssoa.html new file mode 100644 index 0000000..6f4a8f2 --- /dev/null +++ b/doc/s6-dnssoa.html @@ -0,0 +1,65 @@ + + + + + s6-dns: the s6-dnssoa program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnssoa program

+ +

+ s6-dnssoa finds the SOA information associated to a domain. +

+ +

Interface

+ +
+     s6-dnssoa [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-dnssrv.html b/doc/s6-dnssrv.html new file mode 100644 index 0000000..2a88408 --- /dev/null +++ b/doc/s6-dnssrv.html @@ -0,0 +1,65 @@ + + + + + s6-dns: the s6-dnssrv program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnssrv program

+ +

+ s6-dnssrv finds the SRV information associated to a +service name, protocol name and domain name. +

+ +

Interface

+ +
+     s6-dnssrv [ -q ] [ -r ] [ -t timeout ] service proto domain
+
+ + + +

Options

+ + + + + diff --git a/doc/s6-dnstxt.html b/doc/s6-dnstxt.html new file mode 100644 index 0000000..fa84174 --- /dev/null +++ b/doc/s6-dnstxt.html @@ -0,0 +1,77 @@ + + + + + s6-dns: the s6-dnstxt program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-dnstxt program

+ +

+ s6-dnstxt finds the TXT information associated to a domain name. +

+ +

Interface

+ +
+     s6-dnstxt [ -q ] [ -r ] [ -t timeout ] domain
+
+ + + +

Options

+ + + +

Notes

+ +

+ There can be more than one character-string in a TXT RR, and there can be +more than one TXT RR per domain. DNS clients usually concatenate all this +and only give one string. s6-dnstxt concatenates all the character-strings +in one TXT record, but separates different TXT records, printing each one +on a separate line. +

+ + + diff --git a/doc/s6-randomip.html b/doc/s6-randomip.html new file mode 100644 index 0000000..0ad3b46 --- /dev/null +++ b/doc/s6-randomip.html @@ -0,0 +1,57 @@ + + + + + s6-dns: the s6-randomip program + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The s6-randomip program

+ +

+ s6-randomip generates random IP addresses and prints them to +its standard output, one per line. +

+ +

Interface

+ +
+     s6-randomip [ -4 ] [ -6 ] [ -n max ]
+
+ + + +

Options

+ + + +

Notes

+ +

+ s6-randomip can be used in conjunction with +s6-dnsname-filter to stress-test your +DNS architecture. Please use this responsibly and ethically. +

+ + + diff --git a/doc/skadns/index.html b/doc/skadns/index.html new file mode 100644 index 0000000..f02f2dd --- /dev/null +++ b/doc/skadns/index.html @@ -0,0 +1,262 @@ + + + + + s6-dns: the skadns library interface + + + + + + +

+s6-dns
+Software
+skarnet.org +

+ +

The skadns library interface

+ +

+ The skadns library provides an API for asynchronous DNS +resolution. +

+ +

Compiling

+ +