websocket.sh

Copyright (C) 2016-2020 Anton Skshidlevsky (meefik), MIT

The cross platform WebSocket implementation for UNIX shell. It works on busybox and ash for embedded systems (requires installing busybox applets).

На русском / In Russian

Bash shell as a web terminal

Run web server httpd in websocket.sh directory. For JQuery Terminal Emulator:

cd jquery.terminal
WS_SHELL="sh" httpd -p 8080

For xterm.js:

cd xterm.js
telnetd -p 5023 -l "/bin/sh" -f ./issue
WS_SHELL="telnet 127.0.0.1 5023" httpd -p 8080

Open the terminal in browser: http://localhost:8080/

Custom usage

Run websocket.sh:

WS_SHELL="cat" nc -l -p 12010 -e websocket.sh

Use from browser:

var wsPort = 12010;
var ws = new WebSocket('ws://' + location.hostname + ':' + wsPort);
ws.onmessage = function(ev) {
  var textDecoder = new TextDecoder();
  var fileReader = new FileReader();
  fileReader.addEventListener('load', function () {
    var str = textDecoder.decode(fileReader.result);
    console.log('Received data: ', str);
  });
  fileReader.readAsArrayBuffer(ev.data);
}
ws.onopen = function() {
  ws.send('hello');
}

When user closes tab ws disconnect then nc will also exit. You can use -ll with -e for persistent server:

nc -ll -p 12010 -e websocket.sh

Multiple socket connections

You can use busybox inetd for multiple connections to single port for websocket.sh:

export WS_SHELL="/path/to/script.sh"
inetd -e -f /path/to/inetd.conf

The /path/to/inetd.conf may look like:

12010	stream	tcp	nowait	root	/path/to/websocket.sh

Run on Ubuntu

Ubuntu already have busybox with httpd with cgi and nc with -e. So to run the scripts you need to change shebang and add busybox to commands. You can apply the patch:

diff --git a/cgi-bin/init-ws.sh b/cgi-bin/init-ws.sh
index 78fec21..086ecd2 100755
--- a/cgi-bin/init-ws.sh
+++ b/cgi-bin/init-ws.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/busybox sh
let PORT=${HTTP_HOST##*:}
if [ $PORT -eq 0 ]
@@ -6,7 +6,7 @@ then
else
WS_PORT=$(( PORT+1 ))
fi
-nc -l -p ${WS_PORT} -e ../websocket.sh </dev/null >/dev/null &
+busybox nc -l -p ${WS_PORT} -e ../websocket.sh </dev/null >/dev/null &
echo "Content-Type: application/javascript"
diff --git a/cgi-bin/resize b/cgi-bin/resize
index 903768d..ab82f33 100755
--- a/cgi-bin/resize
+++ b/cgi-bin/resize
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/busybox sh
for param in ${QUERY_STRING//&/ }
diff --git a/websocket.sh b/websocket.sh
index affb009..6d86889 100755
--- a/websocket.sh
+++ b/websocket.sh
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/busybox sh
# websocket.sh
# (C) 2016-2018 Anton Skshidlevsky <[email protected]>, MIT

Then to run xterm.js:

busybox telnetd -p 5023 -l "/bin/sh" -f ./issue
WS_SHELL="telnet 127.0.0.1 5023" busybox httpd -p 8080 -f -vv 

Here httpd started with debug mode so you can see any errors in cgi scripts.

Run on Ubuntu without busybox with native tools

In Ubuntu the nc command from netcat-openbsd doesn't have the -e option. You'll need to install ncat package (sudo apt install ncat) and replace nc inside init-ws.sh with ncat.

The /bin/sh in Ubuntu is Dash and it doesn't have read -n option. So you'll need to change shebang to #!/bin/bash