Docs: Move ssl tunnelling guide to its own page [skip ci]

Having the SSL tunneling instructions on the README caused clutter and was
unnecessary.
This commit is contained in:
tt2468 2020-07-03 06:14:41 -07:00
parent 68db13fc24
commit 4f83b73732
2 changed files with 51 additions and 44 deletions

View File

@ -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. 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 ### Possible use cases
- Remote control OBS from a phone or tablet on the same local network - 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) 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 ## Compiling obs-websocket
See the [build instructions](BUILDING.md). See the [build instructions](BUILDING.md).

45
SSL-TUNNELLING.md Normal file
View File

@ -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.