rrda

REST API allowing to perform DNS queries over HTTP
Log | Files | Refs | README | LICENSE

README.md (5811B)


      1                                     ______  ____________________.
      2                                    /     / /                    |
      3                                   /     . /                     |  R
      4                    ________  ____/___  __/_____   _____         |
      5              __  __\__    /__\__    /__\__    /__\\__  \__      |  R
      6               ///   _/   //   _/   //   |/    \\    ._    \     |
      7               _/    \    \_   \    \_   '     /_    |/    //    |  D
      8               \_____/_____/___/_____/__________/____/    /_     |
      9            <---------h7/dS!---- \      . \ -------\\______/     |  A
     10                                  \      \ \                     |
     11                                   \______\ \____________________|
     12 
     13 ## Description
     14 
     15 RRDA is a REST API written in Go allowing to perform DNS queries over HTTP,
     16 and to get reverse PTR records for both IPv4 and IPv6 addresses. It outputs
     17 JSON-encoded DNS responses.
     18 
     19 The API allows to specify which name server to query (either recursive or
     20 authoritative), and can be used as a foundation to build DNS looking glasses.
     21 
     22 RRDA is a recursive acronym for "RRDA REST DNS API".
     23 
     24 ## Requirements
     25 
     26 RRDA requires the following Go libraries:
     27 
     28 - dns: DNS library in Go - https://github.com/miekg/dns
     29 - pat: pattern muxer for Go - https://github.com/bmizerany/pat
     30 
     31 ## Installation
     32 
     33 Build and install with the `go` tool, all dependencies will be automatically
     34 fetched and compiled:
     35 
     36 	go build
     37 	go install rrda
     38 
     39 ## Usage
     40 
     41 By default, RRDA will bind on localhost, port 8080, in HTTP mode.
     42 
     43 	USAGE:
     44 	  -fastcgi
     45 	        Enable FastCGI mode
     46 	  -host string
     47 	        Set the server host (default "127.0.0.1")
     48 	  -port string
     49 	        Set the server port (default "8080")
     50 	  -version
     51 	        Display version
     52 
     53 ## Running RRDA at boot time
     54 
     55 ### Debian init script
     56 
     57 RRDA is bundled with a Debian init script, see: `debian/rrda`
     58 
     59 Copy the `debian/rrda` file in `/etc/init.d` and modify the line containing
     60 `DAEMON=rrda` to specify the path to your RRDA binary.
     61 
     62 To launch the daemon at startup, run:
     63 
     64 	update-rc.d rrda defaults
     65 
     66 ### FreeBSD rc.d script
     67 
     68 RRDA is bundled with a FreeBSD rc.d script, see: `freebsd/rrda`
     69 
     70 Copy the `freebsd/rrda` file in `/usr/local/etc/rc.d` and the RRDA binary in
     71 `/usr/local/sbin`.
     72 
     73 To launch the daemon at startup, add the following line in `/etc/rc.conf`:
     74 
     75 	rrda_enable="YES"
     76 
     77 ## Making Queries
     78 
     79 The following examples assume there is a resolver on localhost listening on port 53.
     80 
     81 ### Getting Resources Records
     82 
     83 URL Scheme: http://server:port/resolver:port/domain/querytype
     84 
     85 - Example (using an IPv4 resolver): http://127.0.0.1:8080/127.0.0.1:53/example.org/ns
     86 - Example (using an IPv6 resolver): http://127.0.0.1:8080/[::1]:53/example.org/ns
     87 
     88 ### Getting Reverse PTR Records (for both IPv4 and IPv6 addresses)
     89 
     90 URL Scheme: http://server:port/resolver:port/x/ip
     91 
     92 - Example (IPv4): http://127.0.0.1:8080/127.0.0.1:53/x/193.0.6.139
     93 - Example (IPv6): http://127.0.0.1:8080/127.0.0.1:53/x/2001:67c:2e8:22::c100:68b
     94 
     95 ## JSONP Support
     96 
     97 RRDA supports JSONP callbacks.
     98 
     99 - Example: http://127.0.0.1:8080/127.0.0.1:53/example.org/ns?callback=rrda
    100 
    101 ## JSON Output Schema
    102 
    103 The output is a JSON object containing the following arrays, representing the
    104 appropriate sections of DNS packets:
    105 
    106 - question
    107 - answer
    108 - authority (omitted if empty)
    109 - additional (omitted if empty)
    110 
    111 ### Question section
    112 
    113 - name
    114 - type
    115 - class
    116 
    117 ### Answer, Authority, Additional sections
    118 
    119 - name
    120 - type
    121 - class
    122 - ttl
    123 - rdlength
    124 - rdata
    125 
    126 ## Client Errors
    127 
    128 When incorrect user input is entered, the server returns an HTTP 400 Error
    129 (Bad Request), along with a JSON-encoded error message.
    130 
    131 - Code 401: Input string could not be parsed
    132 - Code 402: Input string is not a well-formed domain name
    133 - Code 403: Input string is not a valid IP address
    134 - Code 404: Invalid DNS query type
    135 
    136 ### Examples
    137 
    138 	curl http://127.0.0.1:8080/:53/statdns..net/a
    139 	{"code":402,"message":"Input string is not a well-formed domain name"}
    140  
    141 	curl http://127.0.0.1:8080/:53/x/127.0
    142 	{"code":403,"message":"Input string is not a valid IP address"}
    143 
    144 	curl http://127.0.0.1:8080/:53/statdns.net/error
    145 	{"code":404,"message":"Invalid DNS query type"}
    146 
    147 ## Server Errors
    148 
    149 When the DNS server cannot be reached or returns an error, the server returns
    150 an HTTP 500 Error (Internal Server Error), along with a JSON-encoded error
    151 message.
    152 
    153 - Code 501: DNS server could not be reached
    154 - Code 502: The name server encountered an internal failure while processing this request (SERVFAIL)
    155 - Code 503: Some name that ought to exist, does not exist (NXDOMAIN)
    156 - Code 505: The name server refuses to perform the specified operation for policy or security reasons (REFUSED)
    157 
    158 ### Examples
    159 
    160 	curl http://127.0.0.1:8080/127.0.0.2:53/statdns.net/a
    161 	{"code":501,"message":"DNS server could not be reached"}
    162 
    163 	curl http://127.0.0.1:8080/:53/lame2.broken-on-purpose.generic-nic.net/soa
    164 	{"code":502,"message":"The name server encountered an internal failure while processing this request (SERVFAIL)"}
    165 
    166 	curl http://127.0.0.1:8080/:53/statdns.nete/a
    167 	{"code":503,"message":"Some name that ought to exist, does not exist (NXDOMAIN)"}
    168 
    169 	curl http://127.0.0.1:8080/:53/lame.broken-on-purpose.generic-nic.net/soa
    170 	{"code":505,"message":"The name server refuses to perform the specified operation for policy or security reasons (REFUSED)"}
    171 
    172 ## Sites using RRDA
    173 
    174 - StatDNS: Rest DNS API - https://www.statdns.com/api/
    175 - DNS-LG: Multilocation DNS Looking Glass - http://www.dns-lg.com
    176 
    177 ## License
    178 
    179 RRDA is released under the BSD 2-Clause license. See `LICENSE` file for details.
    180 
    181 ## Author
    182 
    183 RRDA is developed by Frederic Cambus
    184 
    185 - Site: https://www.cambus.net
    186 
    187 ## Resources
    188 
    189 Project homepage: https://www.statdns.com
    190 
    191 Latest tarball release: https://www.statdns.com/rrda/rrda-1.1.0.tar.gz
    192 
    193 GitHub: https://github.com/fcambus/rrda