README.md
1# lws minimal ws server raw proxy fallback
2
3This demonstrates how a vhost doing normal http or http(s) duty can be also be
4bound to a specific role and protocol as a fallback if the incoming protocol is
5unexpected for tls or http. The example makes the fallback role + protocol
6an lws plugin that performs raw packet proxying.
7
8By default the fallback in the example will proxy 127.0.0.1:22, which is usually
9your ssh server listen port, on 127.0.0.1:7681. You should be able to ssh into
10port 7681 the same as you can port 22. At the same time, you should be able to
11visit http://127.0.0.1:7681 in a browser (and if you give -s, to
12https://127.0.0.1:7681 while your ssh client can still connect to the same
13port.
14
15## build
16
17To build this standalone, you must tell cmake where the lws source tree
18./plugins directory can be found, since it relies on including the source
19of the raw-proxy plugin.
20
21```
22 $ cmake . -DLWS_PLUGINS_DIR=~/libwebsockets/plugins && make
23```
24
25## usage
26
27Commandline option|Meaning
28---|---
29-d <loglevel>|Debug verbosity in decimal, eg, -d15
30-r ipv4:address:port|Configure the remote IP and port that will be proxied, by default ipv4:127.0.0.1:22
31-s|Configure the server for tls / https and `LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT`
32-h|(needs -s) Configure the vhost also for `LWS_SERVER_OPTION_ALLOW_HTTP_ON_HTTPS_LISTENER`, allowing http service on tls port (caution... it's insecure then)
33-u|(needs -s) Configure the vhost also for `LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS`, so the server issues a redirect to https to clients that attempt to connect to a server configured for tls with http.
34```
35 $ ./lws-minimal-raw-proxy
36[2018/11/30 19:22:35:7290] USER: LWS minimal raw proxy-fallback
37[2018/11/30 19:22:35:7291] NOTICE: Creating Vhost 'default' port 7681, 1 protocols, IPv6 off
38[2018/11/30 19:22:35:7336] NOTICE: callback_raw_proxy: onward ipv4 127.0.0.1:22
39...
40```
41
42```
43 $ ssh -p7681 me@127.0.0.1
44Last login: Fri Nov 30 19:29:23 2018 from 127.0.0.1
45[me@learn ~]$
46```
47
48At the same time, visiting http(s)://127.0.0.1:7681 in a browser works fine.
49
50