samthor / https-forward

A forwarding HTTPS server using Let's Encrypt

(Watch a video about https-forward!)

Provides a forwarding HTTPS server which transparently fetches and caches certificates via Let's Encrypt. This must run on 443 and 80 (http:// just forwards to https://, no forwarding happens unencrypted) and can't coexist with any other web server on your machine.

Why

This is so you can host random and long-lived services publicly on the internet—perfect for other services which are served on http://, don't care about certificates or HTTPS at all, and might be provided by Node or Go on a random high port (e.g., some dumb service running on localhost:8080).

Note! This doesn't magic up domain names. You would use this service only if you're able to point DNS records to the IP address of a machine you're running this on, and that the machine is able to handle incoming requests on port 443 and 80 (e.g., on a home network, you'd have to set up port forwarding on your router).

Install

⚠️ You should probably install this via Snap if you're using Ubuntu or something like it.

Otherwise, you can build the Go binary and see --help for flags. You should restrict the binary's permissions or run it as nobody with a setcap configuration that lets it listen on low ports.

Configuration

If you're using Snap, the configuration file is at /var/snap/https-forward/common/config (which is empty after install). Otherwise, the default configuration is read at /etc/https-forward.

Either way, it should be authored like this:

# hostname            forward-to          optional-basic-auth
host.example.com      localhost:8080
blah.example.com      192.168.86.24:7999  user:pass
user-only.example.com localhost:9002      user       # accepts any password

# Specify host with '.' to suffix all following
.example.com
test                  localhost:9000
under-example         any-hostname-here.com:9000

# Clear the current suffix with a single "." (otherwise below would be "*.example.com.example.com")
.

# You can include ? or * to glob-match domain parts (this does NOT match "-")
*.example.com         localhost:9000
test-v?*.example.com  localhost:9999    # matches "test-v1", "test-v100", but NOT "test-v" or "test-vx-123"

# serves a blank dummy page (but generate https cert, perhaps as a placeholder)
serves-nothing.example.com

(example.com used above purely as an example. You'd replace it with a domain name you controlled, preferably with a wildcard DNS record like *.example.com.)

Restart or send SIGHUP to the binary to reread the config file.

Notes

If incoming HTTPS requests take a long time and then fail, Let's Encrypt might have throttled you. Unfortunately, the autocert client in Go isn't very verbose about this. This happens on a per-domain basis (rather than say, from your client IP), so just try a new domain (even a subdomain).

This service only forwards to http:// hosts, not secure hosts.

Release Instructions

Follow the guide for Go applications. Run snapcraft and it will probably just build.

https-forward's Issues

Restart with snap restart

The docs suggest SIGHUPping the binary to make it reread the config file, but snap restart https-forward is probably easier to remember in the snap's own description (although will actually do a restart rather than just a re-read, so maybe it's not useful for a deployed thing).

Let'sEncrypt has deprecated the ACMEv1 protocol; the snap for this tool needs recompiled against newer Go packages.

Per this Let'sEncrypt post re: "End of Life Plan for ACMEv1", the ACMEv1 protocol is no longer (as of June 2020) allowing cert generation requests for new domains. The issue was announced some time ago and the relevant Go packages were updated back in October 2019, but the https-forward Snap package was unfortunately built shortly before that.

Would it be at all possible for you to recompile and re-publish the Snap package using the latest "golang.org/x/crypto/acme" and "golang.org/x/crypto/acme/autocert" packages?

At the moment, anyone attempting to use https-forward for newly-created domains is seeing the following error in their syslog:

http: TLS handshake error from {{ letsencrypt server ip and port }}: 403 urn:acme:error:unauthorized: Account creation on ACMEv1 is disabled. Please upgrade your ACME client to a version that supports ACMEv2 / RFC 8555. See https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430 for details.