zishuo/nip
1
0
Fork 0
mirror of https://github.com/cunnie/sslip.io.git synced 2025-10-07 16:41:19 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

README is more developer-friendly with Quick Start

Browse Source 
This repo has been forked 36 times, and yet I've done a great disservice
to my would-be developers by not describing how to run/test my code.

This commit addresses that shortcoming by having a _Quick Start_ section
very near the top.

- includes new Ginkgo v2
- includes required `sudo` for Linux
- removed the now-wrong comment about TXT records (there's now a
  plethora of TXT records such as `ip.sslip.io`)
- minor formatting tweaks
This commit is contained in:
Brian Cunnie
2022-03-03 06:22:20 -08:00
parent cd2b14b924
commit 26646f59a4
1 changed files with 39 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@@ -5,14 +5,40 @@
| Production Nameservers | [![ci.nono.io](https://ci.nono.io/api/v1/pipelines/sslip.io/jobs/dns-servers/badge)](https://ci.nono.io/teams/main/pipelines/sslip.io) |
| DNS Server Unit Tests | [![ci.nono.io](https://ci.nono.io/api/v1/pipelines/sslip.io/jobs/unit/badge)](https://ci.nono.io/teams/main/pipelines/sslip.io) |
*sslip.io* is a DNS server that maps specially-crafted DNS A records to IP addresses
(e.g. "127-0-0-1.sslip.io" maps to 127.0.0.1). It is similar to, and inspired by,
[xip.io](http://xip.io/).
*sslip.io* is a DNS server that maps specially-crafted DNS A records to IP
addresses (e.g. "127-0-0-1.sslip.io" maps to 127.0.0.1). It is similar to, and
inspired by, [xip.io](http://xip.io/).
If you'd like to use sslip.io _as a service_, refer to the website
([sslip.io](https://sslip.io)) for more information. This README targets
developers; the website targets users.
## Quick Start
```bash
git clone git@github.com:cunnie/sslip.io.git
cd sslip.io/bosh-release/src/sslip.io-dns-server/
sudo go run main.go
# sudo is required on Linux, but not on macOS, to bind to privileged port 53
```
In another window:
```bash
dig @localhost 192.168.0.1.sslip.io +short
# should return "192.168.0.1"
```
## Quick Start Tests
```bash
go get github.com/onsi/ginkgo/v2/ginkgo
go get github.com/onsi/gomega/...
sudo ~/go/bin/ginkgo -r .
# sudo is required on Linux, but not on macOS, to bind to privileged port 53
```
## Directory Structure
- `src/` contains the source code to the DNS server.
- `ci/` contains the [Concourse](https://concourse.ci/) continuous integration
(CI) pipeline and task.
@@ -35,48 +61,22 @@ the source:
- it binds to port 53 (you can't change it)
- it only binds to UDP (no TCP, sorry)
- The SOA record is hard-coded with the exception of the _MNAME_ (primary master
name server) record, which is set to the queried hostname (e.g. `dig
- The SOA record is hard-coded with the exception of the _MNAME_ (primary
master name server) record, which is set to the queried hostname (e.g. `dig
big.apple.com @ns-aws.nono.io` would return an SOA with an _MNAME_ record of
`big.apple.com.`
- The NS records are hard-coded
- The NS records are hard-coded (`ns-aws.sslip.io`, `ns-azure.sslip.io`,
`ns-gce.sslip.io`)
- The MX records are hard-coded to the queried hostname with a preference of 0,
with the exception of `sslip.io` itself, which has custom MX records to enable
email delivery to ProtonMail.
- No TXT records are returned with the exception of `sslip.io`, which has custom
records to enable email delivery
with the exception of `sslip.io` itself, which has custom MX records to
enable email delivery to ProtonMail
- There are no SRV records
To run the unit tests:
```
cd src
go get github.com/onsi/ginkgo/ginkgo
go get github.com/onsi/gomega/...
ginkgo -r .
```
To run the server on, say, a Mac, you must first start the server:
```
cd src
go run main.go
```
And then, in another window, run a query, e.g.:
```
dig +short 127.0.0.1.sslip.io @localhost
```
Which will return the expected IP address:
```
127.0.0.1
```
You will also see a log message in the server window, similar to the
following:
```
2020/11/22 03:45:44 ::1.62302 TypeA 127.0.0.1.sslip.io. ? 127.0.0.1
```
### Acknowledgements
- Sam Stephenson (xip.io), Roopinder Singh (nip.io), and the other DNS developers out there
- Sam Stephenson (xip.io), Roopinder Singh (nip.io), and the other DNS
developers out there
- The contributors (@normanr, @jpambrun come to mind) who improved sslip.io
- Jenessa Petersen of Let's Encrypt who bumped the rate limits
- Natalia Ershova of JetBrains who provided a free license for [open source development](https://www.jetbrains.com/community/opensource/#support)
- Natalia Ershova of JetBrains who provided a free license for [open source
development](https://www.jetbrains.com/community/opensource/#support)