Restructure inlets TCP/HTTP pages and reduce README length

Signed-off-by: Alex Ellis (OpenFaaS Ltd) <[email protected]>

Author: alexellis

docs/index.md

@@ -44,6 +44,8 @@ Inlets can tunnel either HTTP or TCP traffic:
 * HTTP (L7) tunnels can be used to connect one or more HTTP endpoints from one network to another. A single tunnel can expose multiple websites or hosts, including LoadBalancing and multiple clients to one server.
 * TCP (L4) tunnels can be used to connect TCP services such as a database, a reverse proxy, RDP, Kubernetes or SSH to the Internet. A single tunnel can expose multiple ports on an exit-server and load balance between clients
 
+You'll find tutorials in the navigation for HTTP and TCP tunnels, along with a dedicated section for integrating with Kubernetes.
+
 ### Downloading inlets
 
 inlets is available for Windows, MacOS (Apple Silicon) and Linux:
@@ -52,65 +54,12 @@ inlets is available for Windows, MacOS (Apple Silicon) and Linux:
 
 You can also use [the container image from ghcr.io](https://github.com/orgs/inlets/packages/container/package/inlets-pro): `ghcr.io/inlets/inlets-pro:latest`
 
-### Your first HTTPS tunnel with an automated tunnel server (recommended)
-
-Expose one or more HTTPS domains from your local machine.
-
-* [Tutorial: Expose one or more local HTTP services via HTTPS](https://inlets.dev/blog/2021/08/08/private-tunnel.html)
-
-### Install a HTTP tunnel server manually (advanced)
-
-If you don't want to use automation tools to create a server for the inlets-pro server, then you can follow this manual guide to generate and install a systemd service instead.
-
-* [Tutorial: Setting up a HTTP tunnel server manually](/tutorial/manual-http-server/)
-
-### Tunnel TCP services
-
-inlets is not limited to exposing HTTP connections, you can also tunnel TCP protocols like RDP, VNC, SSH, TLS (i.e. reverse proxies, or the Kubernetes API server) and databases.
-
-* [Tutorial: Expose a private SSH server over a TCP tunnel](/tutorial/ssh-tcp-tunnel/)
-* [Tutorial: Tunnel a private Postgresql database](/tutorial/postgresql-tcp-tunnel/)
-* [Tutorial: Tunnel ports 80 and 443 over TCP for a reverse proxy](https://docs.inlets.dev/tutorial/caddy-http-tunnel/)
-
-### Running multiple tunnel servers on the same host (Advanced)
-
-If you want to mix HTTP and TCP tunnels on the same tunnel server, you could either only use TCP ports, or enable both.
-
-* [Advanced: Setting up dual TCP and HTTPS tunnels](/tutorial/dual-tunnels/)
-
-If you're looking to scale inlets to host many tunnels, then Kubernetes is probably a better option.
-
-### Local port forwarding (Intermediate)
-
-* [Case-study: Reliable local port-forwarding from Kubernetes](https://inlets.dev/blog/2021/04/13/local-port-forwarding-kubernetes.html)
-
-### Connecting with Kubernetes
-
-You may have an on-premises Kubernetes cluster that needs ingress. Perhaps you have a homelab, or Raspberry Pi cluster, that you want to self host services on.
-
-* [Tutorial: Expose a local IngressController with the inlets-operator](/tutorial/kubernetes-ingress/)
-* [Tutorial: Expose Kubernetes services in short-lived clusters with helm](https://inlets.dev/blog/2021/07/08/short-lived-clusters.html)
-
-Some teams want to have dev work like production, with tools Istio working locally just like in the cloud.
-
-* [Tutorial: Expose an Istio gateway with the inlets-operator](/tutorial/istio-gateway)
-
-* [Tutorial: Access the Kubernetes API server from anywhere like managed service](/tutorial/kubernetes-api-server/)
-
-See also: [helm charts](https://github.com/inlets/inlets-pro/tree/master/chart)
-
-### Provide tunnels as a managed service or SaaS
+### Becoming a tunnel provider or operating a hosting service
 
 Inlets Uplink is a complete solution for Kubernetes that makes it quick and easy to onboard hundreds or thousands of tenants. It can also be used to host tunnel servers on Kubernetes, for smaller amounts of tunnels.
 
 Learn more: [Inlets Uplink](https://docs.inlets.dev/uplink/overview/)
 
-### Monitoring and metrics
-
-Inlets offers you multiple options to monitor your tunnels and get insight in their performance. Find out tunnel statistics, uptime and connected clients with the `inlets-pro status` command or collect the Prometheus metrics from the monitoring endpoint.
-
-* [Monitoring and metrics](/tutorial/monitoring-and-metrics)
-
 ## Reference documentation
 
 ### inletsctl

docs/tutorial/automated-tcp-server.md

@@ -0,0 +1,64 @@
+# Create a tunnel server with inletsctl
+
+When should you create a TCP tunnel server?
+
+It is advisable to only tunnel TCP services which include their own encryption such as TLS, SSH, RDP, or a Reverse Proxy. To expose a plaintext HTTP endpoint such as `http://localhost:3000`, use an [HTTPS tunnel](/docs/tutorial/automated-http-server.md) instead which will provide TLS to your end-users.
+
+TCP tunnel servers can be [set up manually](/docs/tutorial/manual-tcp-server.md) or automatically with inletsctl.
+
+This page shows the steps needed to create a tunnel server via inletsctl.
+
+For a step-by-step guide on exposing a TCP service such as SSH, see [Expose SSH over a TCP tunnel](/docs/tutorial/ssh-tcp-tunnel.md).
+
+## Obtain a cloud API token
+
+inletsctl provisions a new cloud VM with inlets preinstalled using cloud-init.
+
+You'll need to obtain an API token from your provider of choice using [the inletsctl reference documentation](/docs/reference/inletsctl.md).
+
+## Create a tunnel server via inletsctl
+
+Once you've obtained an API token, you can create a tunnel server with the following command:
+
+```bash
+export PROVIDER=""
+export REGION=""
+export ACCESS_TOKEN_FILE_PATH=""
+
+inletsctl create \
+    --provider $PROVIDER \
+    --access-token-file $ACCESS_TOKEN_FILE_PATH \
+    --region $REGION \
+    --tcp
+```
+
+This will create a new VM in the London region and install inlets-pro on it.
+
+The command will output a sample command for the `inlets-pro client` command:
+
+## Run the tunnel client
+
+The `inletsctl create` command will output a sample command for the `inlets-pro client` command.
+
+To expose SSH from localhost, add:
+
+```
+ --upstream 127.0.0.1 \
+ --port 2222
+```
+
+To expose SSH from a remote machine on your local network i.e. `192.168.1.20`, add:
+
+```
+ --upstream 192.168.1.20 \
+ --port 2222
+```
+
+To expose ports 80 and 443 from a machine where you have a reverse proxy running such as Caddy, add:
+
+```
+ --upstream 192.168.1.20 \
+ --port 80 \
+ --port 443
+```
+

docs/tutorial/http-authentication.md

@@ -0,0 +1,110 @@
+## Built-in HTTP Authentication
+
+This page applies to inlets-pro 0.10.0 and onwards.
+
+Services exposed over HTTP tunnels can have additional authentication added to them using a mechanism built-into inlets.
+
+The `inlets-pro http` command provides three options:
+
+1. Basic Authentication
+2. Bearer Token Authentication
+3. OAuth
+
+## Basic Authentication
+
+Basic authentication is a simple way to restrict access to your service by requiring a username and password.
+
+When a user visits the URL of the service in a web-browser, they will be prompted to enter a username and password.
+
+If they're using curl, then they can pass the username and password using the `--user` flag.
+
+```bash
+curl --user username:password https://example.com
+```
+
+Or simply pass the username and password as part of the URL:
+
+```bash
+curl https://username:[email protected]
+```
+
+The username has a default of `admin` for brevity, but can be overridden if you like:
+
+```bash
+inlets-pro http client \
+    --basic-auth-username admin \
+    --basic-auth-password password \
+```
+
+You can generate a string password using the `openssl` command:
+
+```bash
+openssl rand -base64 32
+```
+
+## Bearer Token Authentication
+
+If you're exposing an endpoint that does not need to be accessed via a web-browser, then you can use Bearer Token Authentication.
+
+This is useful for exposing endpoints that are used by mobile apps or other non-web clients.
+
+To enable Bearer Token Authentication, you can use the `--bearer-token` flag when starting the `inlets-pro http` command.
+
+```bash
+inlets-pro http client \
+    --bearer-token token \
+```
+
+Both Bearer Token and Basic Authentication can be used together by supplying both flags.
+
+```bash
+inlets-pro http client \
+    --bearer-token token \
+    --basic-auth-username admin \
+    --basic-auth-password password \
+```
+
+## OAuth
+
+With OAuth:
+
+* You can define access for multiple users using usernames or email addresses
+* Avoid managing credentials in your application
+* Use an existing well-known provider for authentication such as GitHub
+
+The OAuth 2.0 flow requires a web-browser, so if you anticipate mixed use, then you can combine it with Bearer Token Authentication, for headless clients.
+
+### Example with GitHub.com
+
+The example below will expose: `http://127.0.0.1:3000` using the domain name `tunnel.example.com`.
+
+In order to use GitHub as the OAuth provider, you need to create a new OAuth application.
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click on "New OAuth App"
+3. Enter a name for the application, for example `inlets-tunnel`
+4. Enter the callback URL, for example `http://tunnel.example.com/_/oauth/callback`
+5. Click on "Register application"
+6. Click "Generate a new client secret"
+
+You will be given a client ID and client secret, which you can use to authenticate with GitHub.
+
+We suggest saving this in a convenient location, for example: `~/.inlets/oauth-client-id` and `~/.inlets/oauth-client-secret`.
+
+```bash
+inlets-pro http client \
+    --oauth-client-id $(cat ~/.inlets/oauth-client-id) \
+    --oauth-client-secret $(cat ~/.inlets/oauth-client-secret) \
+    --upstream tunnel.example.com=http://127.0.0.1:3000 \
+    --oauth-provider github \
+    --oauth-acl alexellis \
+    --oauth-acl [email protected]
+```
+
+Once authenticated, a cookie will be set on the domain i.e. `tunnel.example.com` and the user will be redirected back to the root URL of the service `/`.
+
+The duration of the cookie defaults to 5 minutes, but can be extended.
+
+For the first version, GitHub is the only option available for the `--oauth-provider`. More options will be added over time, based upon requests from users, so if you want to use Google, Facebook, GitLab, etc, send us an email to help with prioritisation.
+
+

docs/tutorial/http-header-modification.md

@@ -0,0 +1,66 @@
+# HTTP Header Modification
+
+This page applies to inlets-pro 0.10.0 and onwards.
+
+When you expose a local service over a HTTP tunnel, it may need the headers of the request or those of the response to be modified.
+
+The `inlets-pro http` command provides a mechanism to modify the headers of the request and response, without having to write an additional proxy to do so.
+
+1. Add a header to the request
+2. Add a header to the response
+3. Remove a header from the request
+4. Remove a header from the response
+
+Each flag is provided in the format of either: `Header` or `Header: Value`, and can be provided multiple times to work on multiple headers.
+
+## Add a header to the request
+
+To add a header to the request, you can use the `--request-header-add` flag.
+
+For instance, if you have a client that calls the exposed service, but needs to add a special header like `X-Special-Header` to the request, you can do the following:
+
+```bash
+inlets-pro http client \
+    --request-header-add "X-Special-Header: 1234567890"
+```
+
+Multiple headers can be added at once:
+
+```bash
+inlets-pro http client \
+    --request-header-add "X-Special-Header: 1234567890" \
+    --request-header-add "X-Another-Header: 0987654321"
+```
+
+## Add a header to the response
+
+To add a header to the HTTP response from the exposed service, you can use the `--response-header-add` flag.
+
+For example, to add a header to the response from the server to enable CORS:
+
+```bash
+inlets-pro http client \
+    --response-header-add "Access-Control-Allow-Origin: *"
+```
+
+## Remove a header from the request
+
+If you do not have control over the request headers because they are being sent by a third-party service or application, you can remove the ones you do not want to send.
+
+Here is how you could remove the User-Agent header for privacy or security reasons:
+
+```bash
+inlets-pro http client \
+    --request-header-remove User-Agent
+```
+
+## Remove a header from the response
+
+Let's say that you're using Caddy, and want to remove the `X-Served-By` header from the request for security or privacy reasons.
+
+To remove a header from the request, you can use the `--request-header-remove` flag.
+
+```bash
+inlets-pro http client \
+  --request-header-remove X-Served-By
+```

docs/tutorial/ip-filtering.md

@@ -0,0 +1,32 @@
+# IP filtering
+
+HTTP and TCP tunnels support filtering of incoming requests by IP address through an allow list.
+
+When enabled, only requests from the specified IP addresses or CIDR ranges will be allowed to connect.
+
+You can read more about this feature [in the announcement](https://inlets.dev/blog/2021/10/15/allow-lists.html)
+
+## How to enable IP filtering
+
+To enable IP filtering, you can use the `--allow-cidr` flag to the inlets-pro http or tcp server commands.
+
+You can log into a [host created by inletsctl](/docs/tutorial/automated-http-server.md), or you can [create a host manually](/docs/tutorial/manual-http-server.md).
+
+The below example allows requests from the IP address `192.168.1.1` and the CIDR range `192.168.2.0/24`.
+
+For HTTP tunnels:
+
+```bash
+inlets-pro http server \
+    --allow-ips 192.168.1.1 \
+    --allow-ips 192.168.1.0/24
+```
+
+For TCP tunnels:
+
+```bash
+inlets-pro tcp server \
+    --allow-ips 192.168.1.1 \
+    --allow-ips 192.168.1.0/24
+```
+