README.md (5769B)
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 ### Identify a Name Server instance 85 86 URL Scheme: http://server:port/resolver:port/id 87 88 - Example (using an IPv4 resolver): http://127.0.0.1:8080/127.0.0.1:53/id 89 - Example (using an IPv6 resolver): http://127.0.0.1:8080/[::1]:53/id 90 91 ## JSONP Support 92 93 RRDA supports JSONP callbacks. 94 95 - Example: http://127.0.0.1:8080/127.0.0.1:53/example.org/ns?callback=rrda 96 97 ## JSON Output Schema 98 99 The output is a JSON object containing the following arrays, representing the 100 appropriate sections of DNS packets: 101 102 - question 103 - answer 104 - authority (omitted if empty) 105 - additional (omitted if empty) 106 107 ### Question section 108 109 - name 110 - type 111 - class 112 113 ### Answer, Authority, Additional sections 114 115 - name 116 - type 117 - class 118 - ttl 119 - rdlength 120 - rdata 121 122 ## Client Errors 123 124 When incorrect user input is entered, the server returns an HTTP 400 Error 125 (Bad Request), along with a JSON-encoded error message. 126 127 - Code 401: Input string could not be parsed 128 - Code 402: Input string is not a well-formed domain name 129 - Code 403: Input string is not a valid IP address 130 - Code 404: Invalid DNS query type 131 132 ### Examples 133 134 curl http://127.0.0.1:8080/:53/statdns..net/a 135 {"code":402,"message":"Input string is not a well-formed domain name"} 136 137 curl http://127.0.0.1:8080/:53/x/127.0 138 {"code":403,"message":"Input string is not a valid IP address"} 139 140 curl http://127.0.0.1:8080/:53/statdns.net/error 141 {"code":404,"message":"Invalid DNS query type"} 142 143 ## Server Errors 144 145 When the DNS server cannot be reached or returns an error, the server returns 146 an HTTP 500 Error (Internal Server Error), along with a JSON-encoded error 147 message. 148 149 - Code 501: DNS server could not be reached 150 - Code 502: The name server encountered an internal failure while processing this request (SERVFAIL) 151 - Code 503: Some name that ought to exist, does not exist (NXDOMAIN) 152 - Code 505: The name server refuses to perform the specified operation for policy or security reasons (REFUSED) 153 154 ### Examples 155 156 curl http://127.0.0.1:8080/127.0.0.2:53/statdns.net/a 157 {"code":501,"message":"DNS server could not be reached"} 158 159 curl http://127.0.0.1:8080/:53/lame2.broken-on-purpose.generic-nic.net/soa 160 {"code":502,"message":"The name server encountered an internal failure while processing this request (SERVFAIL)"} 161 162 curl http://127.0.0.1:8080/:53/statdns.nete/a 163 {"code":503,"message":"Some name that ought to exist, does not exist (NXDOMAIN)"} 164 165 curl http://127.0.0.1:8080/:53/lame.broken-on-purpose.generic-nic.net/soa 166 {"code":505,"message":"The name server refuses to perform the specified operation for policy or security reasons (REFUSED)"} 167 168 ## Sites using RRDA 169 170 - StatDNS: Rest DNS API - https://www.statdns.com/api/ 171 - DNS-LG: Multilocation DNS Looking Glass - http://www.dns-lg.com 172 173 ## License 174 175 RRDA is released under the BSD 2-Clause license. See `LICENSE` file for details. 176 177 ## Author 178 179 RRDA is developed by Frederic Cambus 180 181 - Site: https://www.cambus.net 182 183 ## Resources 184 185 Project homepage: https://www.statdns.com 186 187 Latest tarball release: https://www.statdns.com/rrda/rrda-1.4.0.tar.gz 188 189 GitHub: https://github.com/fcambus/rrda