From 0257ce0dae01fa95a6b690fd91960ce77fd59673 Mon Sep 17 00:00:00 2001 From: Mark Dain Date: Sat, 9 Jan 2021 19:23:18 +0000 Subject: [PATCH] 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 --- README.md | 23 +++++++------- doc/tls-redirector.8 | 72 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 11 deletions(-) create mode 100644 doc/tls-redirector.8 diff --git a/README.md b/README.md index b2afc8f..f7add4c 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/doc/tls-redirector.8 b/doc/tls-redirector.8 new file mode 100644 index 0000000..c24f271 --- /dev/null +++ b/doc/tls-redirector.8 @@ -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) -- 2.30.1