diff --git a/README.md b/README.md index 76af15d7..074c30de 100644 --- a/README.md +++ b/README.md @@ -20,50 +20,6 @@ A web client and frontend made by [t2t2](https://github.com/t2t2/obs-tablet-remo It is **highly recommended** to protect obs-websocket with a password against unauthorized control. To do this, open the "Websocket server settings" dialog under OBS' "Tools" menu. In the settings dialogs, you can enable or disable authentication and set a password for it. -### Connecting over a TLS/secure connection (or remotely) - -**Before doing this, secure the WebSockets server first by enabling authentication with a strong password!** - -If you want to expose the WebSockets server of obs-websocket over a secure TLS connection (or to connect remotely), the easiest approach is to use a localhost tunneling service like [ngrok](https://ngrok.com/) or [pagekite](https://pagekite.net/). - -**Please bear in mind that doing this will expose your OBS instance to the open Internet and the security risks it implies. You've been warned!** - -#### ngrok - -[Install the ngrok CLI tool](https://ngrok.com/download), then start ngrok bound to port 4444 like this: - -```bash -ngrok http 4444 -``` - -The ngrok command will output something like this: - -``` -ngrok by @inconshreveable - -Tunnel Status online -Version 2.0/2.0 -Web Interface http://127.0.0.1:4040 -Forwarding http://TUNNEL_ID.ngrok.io -> localhost:4444 -Forwarding https://TUNNEL_ID.ngrok.io -> localhost:4444 -``` - -Where `TUNNEL_ID` is, as the name implies, the unique name of your ngrok tunnel. You'll get a new one every time you start ngrok. - -Then, use `wss://TUNNEL_ID.ngrok.io` to connect to obs-websocket over TLS. - -See the [ngrok documentation](https://ngrok.com/docs) for more tunneling options and settings. - -#### PageKite - -[Install the PageKite CLI tool](http://pagekite.net/downloads), then start PageKite bound to port 4444 like this (replace NAME with one of your choosing): - -```bash -$ python pagekite.py 4444 NAME.pagekite.me -``` - -Then, use `wss://NAME.pagekite.me` to connect to obs-websocket over TLS. - ### Possible use cases - Remote control OBS from a phone or tablet on the same local network @@ -87,6 +43,12 @@ Here's a list of available language APIs for obs-websocket : I'd like to know what you're building with or for obs-websocket. If you do something in this fashion, feel free to drop a message in `#project-showoff` in the [discord server!](https://discord.gg/WBaSQ3A) +### Securing obs-websocket (via TLS/SSL) + +If you are intending to use obs-websocket outside of a LAN environment, it is highly recommended to secure the connection using a tunneling service. + +See the SSL [tunnelling guide](SSL-TUNNELLING.md) for easy instructions on how to encrypt your websocket connection. + ## Compiling obs-websocket See the [build instructions](BUILDING.md). diff --git a/SSL-TUNNELLING.md b/SSL-TUNNELLING.md new file mode 100644 index 00000000..b841e711 --- /dev/null +++ b/SSL-TUNNELLING.md @@ -0,0 +1,45 @@ +# Connecting over a TLS/secure connection (or remotely) + +If you want to expose the WebSocket server of obs-websocket over a secure TLS connection (or to connect remotely), the easiest approach is to use a localhost tunneling service like [ngrok](https://ngrok.com/) or [pagekite](https://pagekite.net/). + +**Before doing this, secure the WebSocket server first by enabling authentication with a strong password!** + +**Please bear in mind that doing this will expose your OBS instance to the open Internet and the security risks it implies. *You've been warned!*** + + +## ngrok + +[Install the ngrok CLI tool](https://ngrok.com/download) on a linux OS, then start ngrok bound to port 4444 like this: + +```bash +ngrok http 4444 +``` + +The ngrok command will output something like this: + +```text +ngrok by @inconshreveable + +Tunnel Status online +Version 2.0/2.0 +Web Interface http://127.0.0.1:4040 +Forwarding http://TUNNEL_ID.ngrok.io -> localhost:4444 +Forwarding https://TUNNEL_ID.ngrok.io -> localhost:4444 +``` + +Where `TUNNEL_ID` is, as the name implies, the unique name of your ngrok tunnel. You'll get a new one every time you start ngrok. + +Then, use `wss://TUNNEL_ID.ngrok.io` to connect to obs-websocket over TLS. + +See the [ngrok documentation](https://ngrok.com/docs) for more tunneling options and settings. + + +## PageKite + +[Install the PageKite CLI tool](http://pagekite.net/downloads), then start PageKite bound to port 4444 like this (replace NAME with one of your choosing): + +```bash +python pagekite.py 4444 NAME.pagekite.me +``` + +Then, use `wss://NAME.pagekite.me` to connect to obs-websocket over TLS.