README.md (5538B)
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 - chi: lightweight, idiomatic and composable router - https://github.com/go-chi/chi 29 - dns: DNS library in Go - https://github.com/miekg/dns 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. 42 43 USAGE: 44 -host string 45 Set the server host (default "127.0.0.1") 46 -port string 47 Set the server port (default "8080") 48 -timeout int 49 Set the query timeout in ms (default 2000) 50 -version 51 Display version 52 53 ## Running RRDA at boot time 54 55 ### Systemd unit file 56 57 RRDA is bundled with a systemd unit file, see: `systemd/rrda.service` 58 59 Copy the `systemd/rrda.service` file in `/etc/systemd/system` and the RRDA 60 binary in `/usr/local/sbin`. 61 62 To launch the daemon at startup, run: 63 64 systemctl enable rrda 65 66 ## Making Queries 67 68 The following examples assume there is a resolver on localhost listening on port 53. 69 70 ### Getting Resources Records 71 72 URL Scheme: http://server:port/resolver:port/domain/querytype 73 74 - Example (using an IPv4 resolver): http://127.0.0.1:8080/127.0.0.1:53/example.org/ns 75 - Example (using an IPv6 resolver): http://127.0.0.1:8080/[::1]:53/example.org/ns 76 77 ### Getting Reverse PTR Records (for both IPv4 and IPv6 addresses) 78 79 URL Scheme: http://server:port/resolver:port/x/ip 80 81 - Example (IPv4): http://127.0.0.1:8080/127.0.0.1:53/x/193.0.6.139 82 - Example (IPv6): http://127.0.0.1:8080/127.0.0.1:53/x/2001:67c:2e8:22::c100:68b 83 84 ## JSONP Support 85 86 RRDA supports JSONP callbacks. 87 88 - Example: http://127.0.0.1:8080/127.0.0.1:53/example.org/ns?callback=rrda 89 90 ## JSON Output Schema 91 92 The output is a JSON object containing the following arrays, representing the 93 appropriate sections of DNS packets: 94 95 - question 96 - answer 97 - authority (omitted if empty) 98 - additional (omitted if empty) 99 100 ### Question section 101 102 - name 103 - type 104 - class 105 106 ### Answer, Authority, Additional sections 107 108 - name 109 - type 110 - class 111 - ttl 112 - rdlength 113 - rdata 114 115 ## Client Errors 116 117 When incorrect user input is entered, the server returns an HTTP 400 Error 118 (Bad Request), along with a JSON-encoded error message. 119 120 - Code 401: Input string could not be parsed 121 - Code 402: Input string is not a well-formed domain name 122 - Code 403: Input string is not a valid IP address 123 - Code 404: Invalid DNS query type 124 125 ### Examples 126 127 curl http://127.0.0.1:8080/:53/statdns..net/a 128 {"code":402,"message":"Input string is not a well-formed domain name"} 129 130 curl http://127.0.0.1:8080/:53/x/127.0 131 {"code":403,"message":"Input string is not a valid IP address"} 132 133 curl http://127.0.0.1:8080/:53/statdns.net/error 134 {"code":404,"message":"Invalid DNS query type"} 135 136 ## Server Errors 137 138 When the DNS server cannot be reached or returns an error, the server returns 139 an HTTP 500 Error (Internal Server Error), along with a JSON-encoded error 140 message. 141 142 - Code 501: DNS server could not be reached 143 - Code 502: The name server encountered an internal failure while processing this request (SERVFAIL) 144 - Code 503: Some name that ought to exist, does not exist (NXDOMAIN) 145 - Code 505: The name server refuses to perform the specified operation for policy or security reasons (REFUSED) 146 147 ### Examples 148 149 curl http://127.0.0.1:8080/127.0.0.2:53/statdns.net/a 150 {"code":501,"message":"DNS server could not be reached"} 151 152 curl http://127.0.0.1:8080/:53/lame2.broken-on-purpose.generic-nic.net/soa 153 {"code":502,"message":"The name server encountered an internal failure while processing this request (SERVFAIL)"} 154 155 curl http://127.0.0.1:8080/:53/statdns.nete/a 156 {"code":503,"message":"Some name that ought to exist, does not exist (NXDOMAIN)"} 157 158 curl http://127.0.0.1:8080/:53/lame.broken-on-purpose.generic-nic.net/soa 159 {"code":505,"message":"The name server refuses to perform the specified operation for policy or security reasons (REFUSED)"} 160 161 ## Sites using RRDA 162 163 - StatDNS: Rest DNS API - https://www.statdns.com/api/ 164 - DNS-LG: Multilocation DNS Looking Glass - http://www.dns-lg.com 165 166 ## License 167 168 RRDA is released under the BSD 2-Clause license. See `LICENSE` file for details. 169 170 ## Author 171 172 RRDA is developed by Frederic Cambus 173 174 - Site: https://www.cambus.net 175 176 ## Resources 177 178 Project homepage: https://www.statdns.com 179 180 Latest tarball release: https://www.statdns.com/rrda/rrda-1.3.0.tar.gz 181 182 GitHub: https://github.com/fcambus/rrda