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

README tweaks

Browse Source 
- Move "Directory Structure" lower down--it's not terribly useful,
  certainly less useful than the "DNS Server" section.
- Remove the "tidy" turd at the bottom of the page. It adds no value,
  and I'm not sure how it got there in the first place.
- A specific sections for flags such as `-nameservers`
- Add a section about running official Docker containers.
- get rid of the old, deprecated "faq" and "about" pages

[#21]
This commit is contained in:
Brian Cunnie
2022-11-12 08:26:26 -08:00
parent cf650f3824
commit cfb83cb301
4 changed files with 106 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
README.md
View File

@@ -28,7 +28,7 @@ dig @localhost 192.168.0.1.sslip.io +short
# should return "192.168.0.1"
```
## Quick Start Tests
### Quick Start Tests
```bash
go install github.com/onsi/ginkgo/v2/ginkgo@latest
@@ -36,24 +36,26 @@ go get github.com/onsi/gomega/...
~/go/bin/ginkgo -r -p .
```
## Customizing Your Own Nameservers
## Running Your Own Nameservers
You can customize your nameserver and address records (NS, A, and AAAA), which
We can customize our nameserver and address records (NS, A, and AAAA), which
can be particularly useful in an internetless (air-gapped) environment. This can
be done with a combination of the `-nameservers` flag and the `-addresses` flag.
For example, let's say you're the DNS admin for pivotal.io, and you'd like to
For example, let's say we're the DNS admin for pivotal.io, and we'd like to
have a subdomain, "xip.pivotal.io", that does sslip.io-style lookups (e.g.
"127.0.0.1.xip.pivotal.io" would resolve to "127.0.0.1"). Let's say you have two
servers that you've set aside for this purpose:
"127.0.0.1.xip.pivotal.io" would resolve to "127.0.0.1"). Let's say we have two
servers that we've set aside for this purpose:
- ns-sslip-0.pivotal.io, 10.8.8.8 (IPv4)
- ns-sslip-1.pivotal.io, fc88:: (IPv6)
First, you'd delegate the subdomain "xip.pivotal.io" to those nameservers, and
then you'd run the following command run on each of the two servers:
First, we delegate the subdomain "xip.pivotal.io" to our two nameservers, and
then we run the following command run on each of the two servers:
```bash
# after we've cloned our repo
cd src/sslip.io-dns-server
go run main.go \
-nameservers=ns-sslip-0.pivotal.io,ns-sslip-1.pivotal.io \
-addresses ns-sslip-0.pivotal.io=10.8.8.8,ns-sslip-1.pivotal.io=fc88::
@@ -63,9 +65,99 @@ go run main.go \
they won't look up google.com. They are not recursive.** Don't ever configure a
machine to point to these nameservers.
### Running with Docker
Probably the easiest way to run the nameserver is with the official Docker
image,
[cunnie/sslip.io-dns-server](https://hub.docker.com/r/cunnie/sslip.io-dns-server):
```bash
docker run \
-it \
--rm \
-p 53:53/udp \
cunnie/sslip.io-dns-server
```
If we see the error, "`Error starting userland proxy: listen udp4 0.0.0.0:53:
bind: address already in use.`", then we turn off the systemd resolver: `sudo
systemctl stop systemd-resolved`
Let's try a more complicated setup: we're on our workstation, jammy.nono.io,
whose IP addresses are 10.9.9.114 and 2601:646:100:69f0:0:ff:fe00:72. We'd like
our workstation to be the DNS server _and_ be the NS record:
```bash
docker run \
-it \
--rm \
-p 53:53/udp \
cunnie/sslip.io-dns-server \
/usr/sbin/sslip.io-dns-server \
-nameservers jammy.nono.io \
-addresses jammy.nono.io=10.9.9.114,jammy.nono.io=2601:646:100:69f0:0:ff:fe00:72
```
From another machine, we run our DNS lookup to check the NS record, and we see
the expected reply:
```bash
dig ns 127.0.0.1.io @jammy.nono.io +short
...
;; ANSWER SECTION:
127.0.0.1.tx. 604800 IN NS jammy.nono.io.
;; ADDITIONAL SECTION:
jammy.nono.io. 604800 IN A 10.9.9.114
jammy.nono.io. 604800 IN AAAA 2601:646:100:69f0:0:ff:fe00:72
```
The Docker image is multi-platform supporting both x86_64 architecture as well
as ARM64 (AWS Graviton, Apple M1/M2).
## Command-line Flags
- `-port` overrides the default port, 53, which the server binds to. This can
be especially useful when running as a non-privileged user, unable to bind to
privileged ports (<1024) ("`listen udp :53: bind: permission denied`"). For
example, to run the server on port 9553: `go run main.go -port 9553`. To
query, `dig @localhost 127.0.0.1.sslip.io -p 9553`
- `-nameservers` overrides the default NS records `ns-aws.sslip.io`,
`ns-azure.sslip.io`, and `ns-gce.sslip.io`; flag, e.g. `go run main.go
-nameservers ns1.example.com,ns2.example.com`). If you're running your own
nameservers, you probably want to set this. Don't forget to set address
records for the new name servers with the `-addresses` flag (see below).
Exception: `_acme-challenge` records are handled differently to accommodate
the procurement of Let's Encrypt wildcard certificates; you can read more
about that procedure [here](docs/wildcard.md)
- `-addresses` overrides the default A/AAAA (IPv4/IPv6) address records. For
example, here's how we set the IPv4 record & IPv6 record for our nameserver
(in the `-nameservers` example above), ns1.example.com: `-addresses
ns1.example.com=10.8.8.8,ns1.example.com=fc::8888`. Note how we can set
multiple addresses for the same host using the default values—`ns.sslip.io`
has four IP addresses! `-nameservers
sslip.io=78.46.204.247,sslip.io=2a01:4f8:c17:b8f::2,k-v.io=104.155.144.4,ns.sslip.io=52.0.56.137,ns.sslip.io=52.187.42.158,ns.sslip.io=104.155.144.4,ns.sslip.io=2600:1f18:aaf:6900::a,ns-aws.sslip.io=52.0.56.137,ns-aws.sslip.io=2600:1f18:aaf:6900::a,ns-azure.sslip.io=52.187.42.158,ns-gce.sslip.io=104.155.144.4`
- `blocklistURL` overrides the default block list,
(<https://raw.githubusercontent.com/cunnie/sslip.io/main/etc/blocklist.txt>).
It's not necessary to override this if you're in an internetless environment:
if the DNS server can't download the blocklist, it prints out a message and
continues to serve DNS queries.
## DNS Server Miscellany
- it only binds to UDP (no TCP, sorry)
- The SOA record is hard-coded except 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 MX records are hard-coded to the queried hostname with a preference of 0,
except `sslip.io` itself, which has custom MX records to enable email
delivery to ProtonMail
- There are no SRV records
## Directory Structure
- `src/` contains the source code to the DNS server
- `src/sslip.io-dns-server/` contains the source code to the DNS server
- `ci/` contains the [Concourse](https://concourse.ci/) continuous integration
(CI) pipeline and task
- `spec/` contains the tests for the production nameservers. To run
@@ -76,39 +168,6 @@ machine to point to these nameservers.
- `k8s/document_root_sslip.io/` contains the HTML content of the sslip.io website. Please
run `tidy -im -w 120 k8s/document_root_sslip.io/index.html` before submitting pull
requests
- `bosh-release/` _[deprecated]_ contains the [BOSH](https://bosh.io/docs/)
release. BOSH is the mechanism we previously used to deploy the servers, and
the sslip.io BOSH release is a packaging of the DNS server (analogous to a
`.msi`, `.pkg`, `.deb` or `.rpm`)
## DNS Server
The DNS server is written in Golang and can be configured via flags passed to
the command line.
- it binds to port 53, but can be overridden on the command line with the
`-port`, e.g. `go run main.go -port 9553`
- it only binds to UDP (no TCP, sorry)
- The NS records default to `ns-aws.sslip.io`, `ns-azure.sslip.io`,
`ns-gce.sslip.io`; however, they can be overridden via the `-nameservers`
flag, e.g. `go run main.go -nameservers ns1.example.com,ns2.example.com`). If
you override the name servers, don't forget to set address records for the
new name servers with the `-addresses` flag. Exception: `_acme-challenge`
records are handled differently to accommodate the procurement of Let's
Encrypt wildcard certificates; you can read more about that procedure
[here](docs/wildcard.md)
- You can add custom records via the `-addresses` flag; here's a typical
example where we set an IPv4 record & IPv6 record for a single host:
`-addresses
ns-aws.sslip.io.=52.0.56.137,ns-aws.sslip.io.=2600:1f18:aaf:6900::a`
- The SOA record is hard-coded except 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 MX records are hard-coded to the queried hostname with a preference of 0,
except `sslip.io` itself, which has custom MX records to enable email
delivery to ProtonMail
- There are no SRV records
### Acknowledgements

97
k8s/document_root_sslip.io/about.html
View File

@@ -1,97 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.6.0">
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- The above 3 meta tags *must* come first in the head; any
other head content must come *after* these tags -->
<title>About sslip.io</title>
<meta name="description" content="sslip.io">
<meta name="author" content="Brian Cunnie"><!-- cute Green Lock icon -->
<link rel="shortcut icon" type="image/x-icon" href="img/favicon.ico"><!--
Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<!-- Optional theme -->
<link rel="stylesheet" href="css/starter-template.css">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media
queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via
file:// -->
<!--[if lt IE 9]> <script
src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar"
aria-expanded="false" aria-controls="navbar"><span class="sr-only">Toggle navigation</span></button> <a class=
"navbar-brand" href="/">sslip.io</a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li>
<a href="/">Home</a>
</li>
<li>
<a href="faq.html">FAQ</a>
</li>
<li class="active">
<a href="about.html">About</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
<div class="container">
<div class="starter-template">
<h1>About sslip.io</h1>
<p><a href="https://github.com/tylerschultz">Tyler Schultz</a>, <a href="https://github.com/APShirley">Alvaro
Perez-Shirley</a>, and <a href="https://github.com/cunnie">Brian Cunnie</a> created sslip.io on Tuesday August
11, 2015 during a Pivotal Software-sponsored Hack Day. Thanks Pivotal!</p>
<p><a href="https://github.com/sstephenson">Sam Stephenson</a> built <a href="http://xip.io/">xip.io</a>, upon
which much of our code is based. He also suggested the name <i>sslip.io</i>.</p>
<p><a href="https://github.com/justinjsmith">Justin Smith</a> advised us on the security implications of
releasing an SSL certificate and key to the general public.</p>
<div class="row"></div>
<p>© 2015 Brian Cunnie, Pivotal Software</p>
</div>
</div><!-- /.container -->
<!-- Bootstrap core JavaScript ================================================== -->
<!--
Placed at the end of the document so the pages load faster -->
<!-- jQuery
(necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <!--
Latest compiled and minified JavaScript -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script> <!--
IE10 viewport hack for Surface/desktop Windows 8 bug -->
<script src=
"https://raw.githubusercontent.com/twbs/bootstrap/master/docs/assets/js/ie10-viewport-bug-workaround.js"></script>
<!--
Google Analytics -->
<script>
(function(i, s, o, g, r, a, m) {
i['GoogleAnalyticsObject'] = r;
i[r] = i[r] || function() {
(i[r].q = i[r].q || []).push(arguments)
}, i[r].l = 1 * new Date();
a = s.createElement(o), m = s.getElementsByTagName(
o)[0];
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m)
})(window, document, 'script',
'//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-43107212-2', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>

164
k8s/document_root_sslip.io/faq.html
View File

@@ -1,164 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.6.0">
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- The above 3 meta tags *must* come first in the head; any
other head content must come *after* these tags -->
<title>sslip.io FAQ</title>
<meta name="description" content="sslip.io">
<meta name="author" content="Brian Cunnie"><!-- cute Green Lock icon -->
<link rel="shortcut icon" type="image/x-icon" href="img/favicon.ico"><!-- Latest
compiled and minified CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<!-- Optional theme -->
<link rel="stylesheet" href="css/starter-template.css">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media
queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via
file:// -->
<!--[if lt IE 9]> <script
src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar"
aria-expanded="false" aria-controls="navbar"><span class="sr-only">Toggle navigation</span></button> <a class=
"navbar-brand" href="/">sslip.io</a>
</div>
<div id="navbar" class="collapse navbar-collapse">
<ul class="nav navbar-nav">
<li>
<a href="/">Home</a>
</li>
<li class="active">
<a href="faq.html">FAQ</a>
</li>
<li>
<a href="about.html">About</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div>
</nav>
<div class="container">
<div class="starter-template">
<h1>FAQ</h1>
<p class="lead">Do I have to pay to use this service?</p>
<p>No, it's free.</p>
<p class="lead">Can I use this certificate on my commerce website?</p>
<p>Although there's no technical reason why you couldn't use the sslip.io SSL key and certificate for your
commerce web, we <i>strongly</i> recommend against it: the key is publicly available; your traffic isn't secure.
sslip.io's primary purpose is to assist developers who need to test against valid SSL certs, not to safeguard
content.</p>
<p class="lead">My webserver wants a certificate and an "intermediate certificate chain"—where do I get that?</p>
<p>Certain web servers (e.g. <a href="http://www.tenable.com">Tenable's</a> <a href=
"http://www.tenable.com/products/nessus-vulnerability-scanner">Nessus</a> scanner) prefer to split the chained
certificate file (which has three concatenated certificates) into two files: one file containing a single
certificate for the server itself (e.g. the "*.sslip.io" certificate), and a second file containing the
intermediate certificate authorities (e.g. the two COMODO certificate authorities).</p>
<p>You can split the chained certificate file by hand, or you can download them, pre-split, from GitHub:</p>
<ul>
<li>the server <a href=
"https://raw.githubusercontent.com/cunnie/sslip.io/main/ssl/sslip.io.crt.pem">certificate</a> ("*.sslip.io")
</li>
<li>the intermediate certificate <a href=
"https://raw.githubusercontent.com/cunnie/sslip.io/main/ssl/intermediate-ca.crt.pem">chain</a> (the COMODO
CAs)
</li>
</ul>
<p class="lead">Why can't I use dots in my hostname? xip.io lets me use dots.</p>
<p>You can't have dots, but you can have dashes: for example, "www-sf-ca-us-10-9-9-142.sslip.io" will work with
sslip.io's wildcard SSL certificate, but "www.sf.ca.us.10.9.9.142.sslip.io" will not. This is a technical
limitation of wildcard certs and the manner in which browsers treat them (read more <a href=
"http://security.stackexchange.com/questions/10538/what-certificates-are-needed-for-multi-level-subdomains">here</a>).</p>
<p>This restricts sslip.io's usage model. For example, it won't work properly with Cloud Foundry's app domain or
system domain.</p>
<p class="lead">Does sslip.io work with name-based virtual hosting? We have multiple projects but only one
webserver.</p>
<p>sslip.io interoperates quite well with <a href=
"https://en.wikipedia.org/wiki/Virtual_hosting#Name-based">name-based virtual hosting</a>. You can prepend
identifying information to the sslip.io hostname without jeopardizing the address resolution, and then use those
hostnames to distinguish the content being served. For example, let's assume that your webserver's IP address is
10.9.9.30, and that you have three projects you're working on (Apple, Google, and Facebook). You would use the
following three sslip.io hostnames:</p>
<ul>
<li>apple-10-9-9-30.sslip.io</li>
<li>facebook-10-9-9-30.sslip.io</li>
<li>google-10-9-9-30.sslip.io</li>
</ul>
<p class="lead">Can you make the hostnames easier to remember? It's as hard as memorizing IP addresses.</p>
<p>Unfortunately, no. We appreciate that "52-0-56-137.sslip.io" is not an easy-to-remember hostname, whereas
something along the lines of "aws-server.sslip.io" would be much simpler, but we don't see an easy solution—we
need to be able to extract the IP address from the hostname in order for our DNS nameserver to reply with the
proper address when queried.</p>
<p class="lead">Do you have support for IPv6-style addresses?</p>
<p>Not yet, but if there's enough demand for it we might try implementing it.</p>
<p class="lead">Why did you choose a 4096-bit key instead of a 2048-bit key?</p>
<p>We couldn't help ourselves—when it comes to keys, longer is better. In retrospect there were flaws in our
thinking: certain hardware devices, e.g. YubiKeys, only support keys of length 2048 bits or less. Also, there was
no technical value in making a long key—it's publicly available on GitHub, so a zero-bit key would have been
equally secure.</p>
<p class="lead">Do I have to use the sslip.io domain? I'd rather have a valid cert for my domain.</p>
<p>If you want valid SSL certificate, and you don't want to use the sslip.io domain, then you'll need to purchase
a certificate for your domain. We purchased ours from <a href="https://www.cheapsslshop.com">Cheap SSL Shop</a>,
but use a vendor with whom you're comfortable.</p>
<p class="lead">What is the sslip.io certificate chain?</p>
<p>The sslip.io certificate chain is the series of certificates, each signing the next, with a root certificate
at the top. It looks like the following:</p>
<div class="col-sm-12"><img src="img/cert_chain.png" height="206"></div>
<div class="row"></div>
<p>Note that the "root" certificate is "AddTrust's External CA Root", which issued a certificate to the "COMODO
RSA Certification Authority", which in turn issued a certificate to the "COMODO RSA Domain Validation Secure
Server CA" which in turn issued our certificate, "*.sslip.io".</p>
<p class="lead">How is "sslip.io" pronounced?</p>
<p>ESS-ESS-ELL-EYE-PEE-DOT-EYE-OH</p>
<p class="lead">Where do I report bugs? I think I found one.</p>
<p>Open an issue on <a href="https://github.com/cunnie/sslip.io/issues">GitHub</a>; we're tracking our issues
there.</p>
<p class="lead">There's a typo/mistake on the sslip.io website.</p>
<p>Thanks! We love <a href="https://github.com/cunnie/sslip.io/pulls">pull requests</a>.</p>
<div class="row"></div>
<p>© 2015 Brian Cunnie, Pivotal Software</p>
</div>
</div><!-- /.container -->
<!-- Bootstrap core JavaScript ================================================== -->
<!--
Placed at the end of the document so the pages load faster -->
<!-- jQuery
(necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <!--
Latest compiled and minified JavaScript -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script> <!--
IE10 viewport hack for Surface/desktop Windows 8 bug -->
<script src=
"https://raw.githubusercontent.com/twbs/bootstrap/master/docs/assets/js/ie10-viewport-bug-workaround.js"></script>
<!--
Google Analytics -->
<script>
(function(i, s, o, g, r, a, m) {
i['GoogleAnalyticsObject'] = r;
i[r] = i[r] || function() {
(i[r].q = i[r].q || []).push(arguments)
}, i[r].l = 1 * new Date();
a = s.createElement(o), m = s.getElementsByTagName(
o)[0];
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m)
})(window, document, 'script',
'//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-43107212-2', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>

15
k8s/document_root_sslip.io/index.html
View File

@@ -232,11 +232,11 @@ dig @ns.sslip.io txt ip.sslip.io +short -6 # forces IPv6 lookup; sample reply "2
sslip.io software by querying the TXT record of <code>version.status.sslip.io</code>:
<pre>
dig @ns-gce.nono.io version.status.sslip.io txt +short
"2.6.0"
"2022/07/14-18:25:29-0700"
"6512ebd"
"2.6.1"
"2022/11/11-11:39:10-0800"
"b9f0da8"
</pre>
<p>The first number, ("2.6.0"), is the version of the sslip.io DNS software, and is most relevant. The other two
<p>The first number, ("2.6.1"), is the version of the sslip.io DNS software, and is most relevant. The other two
numbers are the date compiled and the most recent git hash, but those values can differ across servers due to the
manner in which the software is deployed.</p>
<h4 id="metrics">Server Metrics</h4>You can retrieve metrics from a given server by querying the TXT records of
@@ -380,11 +380,6 @@ Placed at the end of the document so the pages load faster -->
'//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-43107212-2', 'auto');
ga('send', 'pageview');
</script>About HTML Tidy: https://github.com/htacg/tidy-html5 Bug reports and comments:
https://github.com/htacg/tidy-html5/issues Official mailing list: https://lists.w3.org/Archives/Public/public-htacg/
Latest HTML specification: http://dev.w3.org/html5/spec-author-view/ Validate your HTML documents:
http://validator.w3.org/nu/ Lobby your company to join the W3C: http://www.w3.org/Consortium Do you speak a language
other than English, or a different variant of English? Consider helping us to localize HTML Tidy. For details please
see https://github.com/htacg/tidy-html5/blob/master/README/LOCALIZE.md
</script>
</body>
</html>