~ancarda/tls-redirector

0257ce0dae01fa95a6b690fd91960ce77fd59673 — Mark Dain 12 days ago d1f22ec
Implement basic man page

This commit adds a simple man page that may be copied into
/usr/share/man/man8 where it will become accessible by typing:

    man tls-redirector

The man page contains the same information that is in README.md.

Issue: https://todo.sr.ht/~ancarda/tls-redirector/18
2 files changed, 84 insertions(+), 11 deletions(-)

M README.md
A doc/tls-redirector.8
M README.md => README.md +12 -11
@@ 5,22 5,22 @@
[![Go Report Card](https://goreportcard.com/badge/github.com/ancarda/tls-redirector)](https://goreportcard.com/report/github.com/ancarda/tls-redirector)
[![Docker](https://img.shields.io/docker/pulls/ancarda/tls-redirector)](https://hub.docker.com/r/ancarda/tls-redirector)

tls-redirector is a tiny HTTP server written in Go that is designed to run on
TLS Redirector is a tiny HTTP server written in Go that is designed to run on
port 80 and redirect all incoming traffic to HTTPS. It does this by emitting a
301 Permanent Redirect where the scheme is simply replaced with "https".

This is intended to separate out responsibilities from the software that
listens on port 443 and serves your website. Because you have tls-redirector
listens on port 443 and serves your website. Because you have TLS Redirector
on port 80, you do not need to configure HTTP to HTTPS redirects; simplifying
configuration for Apache, nginx, or whatever web server you use.

Furthermore, most crawlers and bots will actually connect to port 80 without a
meaningful Host header. As tls-redirector cannot be configured, it can only
meaningful Host header. As TLS Redirector cannot be configured, it can only
politely tell them to go away, whereas your primary web server likely sends
them to the "default server" which may well redirect them to your website,
opening you up to being scanned. This causes tons of noise in your log files.

Because it uses the Host header, tls-redirector is truly zero-config. Set it
Because it uses the Host header, TLS Redirector is truly zero-config. Set it
up once and forget about it.

## Useful Links


@@ 54,8 54,9 @@ Building without that tag will produce a binary that only has TCP/IP support.

## Possible Caveats

* The `Host` header is required to redirect - there's no way to configure a
  default - and visitors without one will simply see an error message.
* The `Host` header is required to redirect as there's no way to configure a
  default. Visitors without one will simply see an error message. This message
  is specified in the program source code and cannot be configured at runtime.

* Only a single ACME challenge directory can be served, as the `Host` header
  is ignored, so if you have multiple domains or servers on the same machine,


@@ 70,16 71,16 @@ Behavior may be configured through the following environmental variables:
* `PORT`. TCP/IP port number to listen on. If not specified, port 80 is used
  OR systemd socket activation is detected and used.

  You can force tls-redirector to use socket activation with `PORT=systemd`.
  You can force TLS Redirector to use socket activation with `PORT=systemd`.

* `ACME_CHALLENGE_DIR` Path to a directory on disk to serve at the
  path `/.well-known/acme-challenge`. All files are served as `text/plain` and
  is intended to provide support for HTTP based ACME challenges if necessary.

  Setting this to `/tmp` means tls-redirector will look for files in that
  directory. This differs slightly from the `--webroot` command of EFF certbot
  because certbot expects to be at the root, and tls-redirector does not.
  Therefore, when you setup certbot, if you have the following:
  Setting this to `/tmp` means TLS Redirector will look for files in that
  directory. This differs slightly from the `--webroot` command of EFF Certbot
  because Certbot expects to be at the root, and TLS Redirector does not.
  Therefore, when you setup Certbot, if you have the following:

  `certbot --webroot /var/www`


A doc/tls-redirector.8 => doc/tls-redirector.8 +72 -0
@@ 0,0 1,72 @@
.\"
.\" This is a man page, and can be viewed by invoking "man ./file"
.\"
.TH tls-redirector 8 "09 Jan 2021" "2.4" "tls-redirector man page"
.SH NAME
tls-redirector \- Tiny service for port 80 that rewrites URLs to HTTPS

.\"-------------------
.SH SYNOPSIS
tls-redirector [--help] [--version]

.\"-------------------
.SH DESCRIPTION
TLS Redirector is a tiny HTTP server written in Go that is designed to run on
port 80 and redirect all incoming traffic to HTTPS. It does this by emitting a
301 Permanent Redirect where the scheme is simply replaced with "https".

This is intended to separate out responsibilities from the software that
listens on port 443 and serves your website. Because you have TLS Redirector
on port 80, you do not need to configure HTTP to HTTPS redirects; simplifying
configuration for Apache, nginx, or whatever web server you use.

Furthermore, most crawlers and bots will actually connect to port 80 without a
meaningful Host header. As TLS Redirector cannot be configured, it can only
politely tell them to go away, whereas your primary web server likely sends
them to the "default server" which may well redirect them to your website,
opening you up to being scanned. This causes tons of noise in your log files.

Because it uses the Host header, TLS Redirector is truly zero-config. Set it
up once and forget about it.

.\"-------------------
.SH OPTIONS
Behavior may be configured through the following environmental variables:

PORT. TCP/IP port number to listen on. If not specified, port 80 is used OR
systemd socket activation is detected and used. You can force TLS Redirector
to use socket activation with PORT=systemd. Support for socket activation must
be compiled in.

ACME_CHALLENGE_DIR. Path to a directory on disk to serve at the path
/.well-known/acme-challenge. All files are served as text/plain and is
intended to provide support for HTTP based ACME challenges if necessary.
Setting this to /tmp means TLS Redirector will look for files in that
directory. This differs slightly from the --webroot command of EFF Certbot
because Certbot expects to be at the root, and TLS Redirector does not.
Therefore, when you setup Certbot, if you have the following:

    certbot --webroot /var/www

You should set TLS Redirector thusly:

    ACME_CHALLENGE_DIR=/var/www/.well-known/acme-challenge

.\"-------------------
.SH SEE ALSO
Project hub: https://sr.ht/~ancarda/tls-redirector

.\"-------------------
.SH BUGS
The Host header is required to redirect as there's no way to configure a
default. Visitors without one will simply see an error message. This message
is specified in the program source code and cannot be configured at runtime.

Only a single ACME challenge directory can be served, as the Host header is
ignored, so if you have multiple domains or servers on the same machine, you
may want to consider using DNS based ACME challenges or store all your HTTP
based ACME challenges in the same directory.

.\"-------------------
.SH AUTHOR
Mark Dain (mark@markdain.net)