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