Merge branch 'main' of github.com:openziti/zrok

docs/v0.3_getting_started/getting_started.md

@@ -323,7 +323,7 @@ And now if we refresh the frontend endpoint URL in the web browser, we'll see an
 
 ![zrok docs share](images/zrok_docs_share.png)
 
-With the reserved share, we're free stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share.
+With the reserved share, we're free to stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share.
 
 When we're done with the reserved share, we can _release_ it using this command:
 

docs/v0.3_nginx_tls_guide.md

@@ -0,0 +1,88 @@
+# Nginx Reverse Proxy for zrok
+
+I'll assume you have a running zrok controller and public frontend and wish to front both with Nginx providing server TLS. Go back to [the hosting quickstart](v0.3_quickstart.md) if you still need to spin those up.
+
+## Choose a Reverse Proxy Address
+
+I'll use `https://api.zrok.quigley.com:443` in this example, and assume you already set up wildcard DNS like `*.zrok.quigley.com`. This lets us elect `api.zrok.quigley.com` as the controller DNS name, and forward any other incoming requests to the zrok public frontend.
+
+## Obtain a Wildcard Server Certificate
+
+You must complete a DNS challenge to obtain a wildcard certificate from Let's Encrypt. I'll assume you know how to create the necessary TXT record in the DNS zone you're using with zrok.
+
+1. Install certbot: https://eff-certbot.readthedocs.io/en/stable/install.html
+2. Run certbot with the manual plugin: https://certbot.eff.org/docs/using.html#manual
+
+    ```bash
+    # install cert for *.zrok.quigley.com in /etc/letsencrypt
+    sudo certbot certonly --manual
+    ````
+
+## [Install Nginx](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/)
+
+## Configure Nginx
+
+```
+server {
+    listen              443 ssl;
+    server_name         api.zrok.quigley.com;
+    ssl_certificate     /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
+    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
+    ssl_ciphers         HIGH:!aNULL:!MD5;
+
+    location / {
+      proxy_pass      http://127.0.0.1:18080;
+      error_log       /var/log/nginx/zrok-controller.log;
+    }
+
+}
+
+server {
+    listen              443 ssl;
+    server_name         *.zrok.quigley.com;
+    ssl_certificate     /etc/letsencrypt/live/zrok.quigley.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/zrok.quigley.com/privkey.pem;
+    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
+    ssl_ciphers         HIGH:!aNULL:!MD5;
+
+    location / {
+      proxy_pass       http://127.0.0.1:8080;
+      proxy_set_header Host $host;
+      error_log        /var/log/nginx/zrok-frontend.log;
+      proxy_busy_buffers_size   512k;
+      proxy_buffers    4 512k;
+      proxy_buffer_size   256k;
+
+    }
+
+}
+```
+
+## Restart Nginx
+
+Load the new configuration by restarting Nginx. Check the logs to make sure it's happy.
+
+> Started A high performance web server and a reverse proxy server.
+
+## Check the Firewall
+
+If you followed the non-TLS quickstart then you may have opened 8080,108080/tcp in your firewall. You can go ahead and replace those exceptions with 443/tcp because only Nginx needs to be reachable for zrok to function.
+
+## Update the zrok Frontend
+
+List available frontends to obtain the token identifier of the frontend named "public". You may need to set `ZROK_ADMIN_TOKEN` or `ZROK_API_ENDPOINT` before running `zrok admin`.
+
+```bash
+$ zrok admin list frontends
+
+ TOKEN         ZID        PUBLIC NAME  URL TEMPLATE                              CREATED AT                         UPDATED AT                    
+ 2NiDTRYUww18  7DsLh9DXG  public       http://{token}.zrok.quigley.com:8080  2023-01-19 05:29:20.793 +0000 UTC  2023-01-19 06:17:25 +0000 UTC 
+```
+
+Update the URL template to use Nginx.
+
+```bash
+$ zrok admin update frontend 2NiDTRYUww18 --url-template https://{token}.zrok.quigley.com:443
+[   0.028]    INFO main.(*adminUpdateFrontendCommand).run: updated global frontend '2NiDTRYUww18'
+```

docs/v0.3_self_hosting_guide.md

@@ -21,7 +21,7 @@ You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when bu
 
 ## Configure the Controller
 
-Create a controller configuration file in `etc/ctrl.yml`.
+Create a controller configuration file in `etc/ctrl.yml`. The controller does not provide server TLS, but you may front the server with a reverse proxy. This example will expose the non-TLS listener for the controller.
 
 ```yaml
 #    _____ __ ___ | | __
@@ -144,7 +144,7 @@ Now our `zrok` controller is fully configured.
 
 ## Configure the Public Frontend
 
-Create `etc/http-frontend.yml`. You must reiterate the pattern you expressed in the public frontend URL template as a `host_match` pattern, and you may change the default address where the frontend will listen for public access requests.
+Create `etc/http-frontend.yml`. You must reiterate the pattern you expressed in the public frontend URL template as a `host_match` pattern, and you may change the default address where the frontend will listen for public access requests. The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the `Host` header supplied by the viewer. This example will expose the non-TLS listener for the frontend.
 
 ```yaml
 host_match: zrok.quigley.com