From cfb83cb301ada35b46ef90c19dc323b7db88325c Mon Sep 17 00:00:00 2001 From: Brian Cunnie Date: Sat, 12 Nov 2022 08:26:26 -0800 Subject: [PATCH] README tweaks - 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] --- README.md | 143 +++++++++++++++------- k8s/document_root_sslip.io/about.html | 97 --------------- k8s/document_root_sslip.io/faq.html | 164 -------------------------- k8s/document_root_sslip.io/index.html | 15 +-- 4 files changed, 106 insertions(+), 313 deletions(-) delete mode 100644 k8s/document_root_sslip.io/about.html delete mode 100644 k8s/document_root_sslip.io/faq.html diff --git a/README.md b/README.md index fca2ec3..b9959f7 100644 --- a/README.md +++ b/README.md @@ -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, + (). + 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 diff --git a/k8s/document_root_sslip.io/about.html b/k8s/document_root_sslip.io/about.html deleted file mode 100644 index 0387a06..0000000 --- a/k8s/document_root_sslip.io/about.html +++ /dev/null @@ -1,97 +0,0 @@ - - - - - - - - - About sslip.io - - - - - - - - - - - - -
-
-

About sslip.io

-

Tyler Schultz, Alvaro - Perez-Shirley, and Brian Cunnie created sslip.io on Tuesday August - 11, 2015 during a Pivotal Software-sponsored Hack Day. Thanks Pivotal!

-

Sam Stephenson built xip.io, upon - which much of our code is based. He also suggested the name sslip.io.

-

Justin Smith advised us on the security implications of - releasing an SSL certificate and key to the general public.

-
-

© 2015 Brian Cunnie, Pivotal Software

-
-
- - - - - - - - - - - - - diff --git a/k8s/document_root_sslip.io/faq.html b/k8s/document_root_sslip.io/faq.html deleted file mode 100644 index 1a86377..0000000 --- a/k8s/document_root_sslip.io/faq.html +++ /dev/null @@ -1,164 +0,0 @@ - - - - - - - - - sslip.io FAQ - - - - - - - - - - - - -
-
-

FAQ

-

Do I have to pay to use this service?

-

No, it's free.

-

Can I use this certificate on my commerce website?

-

Although there's no technical reason why you couldn't use the sslip.io SSL key and certificate for your - commerce web, we strongly 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.

-

My webserver wants a certificate and an "intermediate certificate chain"—where do I get that?

-

Certain web servers (e.g. Tenable's Nessus 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).

-

You can split the chained certificate file by hand, or you can download them, pre-split, from GitHub:

-
    -
  • the server certificate ("*.sslip.io") -
    • -
  • the intermediate certificate chain (the COMODO - CAs) -
    • -
-

Why can't I use dots in my hostname? xip.io lets me use dots.

-

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 here).

-

This restricts sslip.io's usage model. For example, it won't work properly with Cloud Foundry's app domain or - system domain.

-

Does sslip.io work with name-based virtual hosting? We have multiple projects but only one - webserver.

-

sslip.io interoperates quite well with name-based virtual hosting. 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:

-
    -
  • apple-10-9-9-30.sslip.io
    • -
  • facebook-10-9-9-30.sslip.io
    • -
  • google-10-9-9-30.sslip.io
    • -
-

Can you make the hostnames easier to remember? It's as hard as memorizing IP addresses.

-

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.

-

Do you have support for IPv6-style addresses?

-

Not yet, but if there's enough demand for it we might try implementing it.

-

Why did you choose a 4096-bit key instead of a 2048-bit key?

-

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.

-

Do I have to use the sslip.io domain? I'd rather have a valid cert for my domain.

-

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 Cheap SSL Shop, - but use a vendor with whom you're comfortable.

-

What is the sslip.io certificate chain?

-

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:

-
-
-

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".

-

How is "sslip.io" pronounced?

-

ESS-ESS-ELL-EYE-PEE-DOT-EYE-OH

-

Where do I report bugs? I think I found one.

-

Open an issue on GitHub; we're tracking our issues - there.

-

There's a typo/mistake on the sslip.io website.

-

Thanks! We love pull requests.

-
-

© 2015 Brian Cunnie, Pivotal Software

-
-
- - - - - - - - - - - - - diff --git a/k8s/document_root_sslip.io/index.html b/k8s/document_root_sslip.io/index.html index b169408..b1f47e7 100644 --- a/k8s/document_root_sslip.io/index.html +++ b/k8s/document_root_sslip.io/index.html @@ -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 version.status.sslip.io: 
 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"
-

The first number, ("2.6.0"), is the version of the sslip.io DNS software, and is most relevant. The other two +

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.

Server Metrics

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'); - 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 +