maxmcd / webtty

Share a terminal session over WebRTC

WebTTY

WebTTY allows you to share a terminal session from your machine using WebRTC. You can pair with a friend without setting up a proxy server, debug servers behind NATs, and more. WebTTY also works in-browser. You can connect to a WebTTY session from this static page: https://maxmcd.github.io/webtty/

Status

There are a handful of bugs to fix, but everything works pretty well at the moment. Please open an issue if you find a bug.

Installation

Download a binary from the releases page: https://github.com/maxmcd/webtty/releases

Or, install directly with Go. WebTTY requires Go version 1.9 or higher.

For Go versions below 1.7:

go get -u github.com/maxmcd/webtty

For Go versions 1.7 and up:

go install github.com/maxmcd/webtty@latest

There were recent breaking api changes in the pion/webrtc library. Make sure to run go get -u github.com/pion/webrtc if you're running into any installation errors.

Running

> webtty -h
Usage of webtty:
  -cmd
        The command to run. Default is "bash -l"
        Because this flag consumes the remainder of the command line,
        all other args (if present) must appear before this flag.
        eg: webtty -o -v -ni -cmd docker run -it --rm alpine:latest sh
  -ni
        Set host to non-interactive
  -non-interactive
        Set host to non-interactive
  -o    One-way connection with no response needed.
  -s string
        The stun server to use (default "stun:stun.l.google.com:19302")
  -v    Verbose logging

On the host computer

> webtty
Setting up a WebTTY connection.

Connection ready. Here is your connection data:

25FrtDEjh7yuGdWMk7R9PhzPmphst7FdsotL11iXa4r9xyTM4koAauQYivKViWYBskf8habEc5vHf3DZge5VivuAT79uSCvzc6aL2M11kcUn9rzb4DX4...

Paste it in the terminal after the webtty command
Or in a browser: https://maxmcd.github.io/webtty/

When you have the answer, paste it below and hit enter.

On the client computer

> webtty 25FrtDEjh7yuGdWMk7R9PhzPmphst7FdsotL11iXa4r9xyTM4koAauQYivKViWYBskf8habEc5vHf3DZge5VivuAT79uSCvzc6aL2M11kcUn9rzb4DX4...

Terminal Size

By default WebTTY forces the size of the client terminal. This means the host size can frequently render incorrectly. One way you can fix this is by using tmux:

tmux new-session -s shared
# in another terminal
webtty -ni -cmd tmux attach-session -t shared

Tmux will now resize the session to the smallest terminal viewport.

One-way Connections

One-way connections can be enabled with the -o flag. A typical webrtc connection requires an SDP exchange between both parties. By default, WebTTY will create an SDP offer and wait for you to enter the SDP answer. With the -o flag the initial offer is sent along with a public url that the receiver is expected to post their response to. This uses my service 10kb.site. The host then polls the url continually until it gets an answer.

I think this somewhat violates the spirit of this tool because it relies on a third party service. However, one-way connections allow you to do very cool things. Eg: I can have a build server output a WebTTY connection string on error and allow anyone to attach to the session.

SDP descriptions are encrypted when uploaded and encryption keys are shared with the connection data to decrypt. So presumably the service being compromised is not problematic.

Very open to any ideas on how to enable trusted one-way connections. Please open an issue or reach out if you have thoughts. For now, the -o flag will print a warning and link to this explanation.

webtty's Issues

Azure pipelines truncates connection data

Webtty is awesome. Thank you! I'm trying to use it with Azure Pipelines but unfortunately, the connection data string is truncated in the logs. Is it possible to add a parameter to wrap the output?
Or perhaps you have a suggestion about a different way to solve this? Usually, there is a "view raw log" option in Azure Pipelines but that option is not visible because the task (./webtty -o -ni) is still running.

If I can cancel the pipeline then I can see the entire string but that is not useful because the host connection has now closed.

Help Needed - Web-Client Always Throws Error "Function Import Requires a Callable"

I am facing an issue with my web-client where it always throws an error "Function Import Requires a Callable". I have tried to resolve it by changing two different computers but it still persists. My web-client address is https://jerryokk.github.io/webtty/ and I have attached a screenshot for your reference (👇👇👇).

Can you please help me fix this issue?

Versions:
npm version: 6.14.4
Node.js version: v10.19.0
Go version: 1.20.1

Disable circle-ci testers

Hey @maxmcd mind disabling these? I am not an admin so doesn't look like I can.

I do have all the access I need for setting up the Github Actions testers. I have Go building, and will work on getting nodejs building (need to update WASM code)

thanks

Upgrade to pion/webrtc@v3

I am going to submit a PR to upgrade webtty to pion/webrtc v3

I had to make two changes to the code to accommodate API breakage

• Trickle ICE is enabled by default, used webrtc.GatheringCompletePromise to simulate old behavior
• A application media section isn't created by default anymore. We create a unused DataChannel when offering

Setup code coverage

We just need to add the following to our go test

-coverprofile=cover.out -covermode=atomic

Then use this action after the tests run

      - uses: codecov/codecov-action@v1
        with:
          file: ./cover.out
          name: codecov-umbrella
          fail_ci_if_error: true
          flags: go

SDP Use and Security Clarifications

This is really cool.
If I understand the sdp key exchange, it would be possible for a service to gen a key as a QR code and the developer to scan it and save it to a secure location on their laptop.
Then the service can be deployed somewhere with the public key.
Then when you want to connect to that server you just use the QR code, decrypt it to text and connect.

Please let me know if that's a reasonable thing based on how sdp and this software works
I can then make a little demo and PR it if you want

Connection hangs

I only see these messages when typing as client:

Failed to push SCTP packet: Failed handling chunk: Failure handling SACK: SACK Cumulative ACK 3408757062 is older than ACK point 3408757062

Webtty on web example does not work?

In both firefox and chrome, I get an error at https://maxmcd.github.io/webtty/, whenever I try to paste the offer message...

InvalidParameterError: Empty or null SDP provided to setLocalDescription
InvalidStateError: setRemoteDescription not called

error on web https://maxmcd.github.io/webtty/

The only thing I did is pasting the code

unexpected end of JSON input

When entering the response of the client, I get 'Quitting with an unexpected error: "unexpected end of JSON input"'.

Webclient connect disconnected

I use the branch master code and build.The webclient can not connected
the host:

the web client

Support for macOS?

This does not seem to build for macOS 😢

$ go install github.com/maxmcd/webtty@master
go: downloading github.com/maxmcd/webtty v0.4.2-0.20210101200840-72801c8b8bc1
# golang.org/x/sys/unix
go/pkg/mod/golang.org/x/[email protected]/unix/syscall_darwin.1_13.go:29:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.1_13.go:27:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.1_13.go:40:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:28:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:43:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:59:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:75:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:90:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:105:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:121:3: //go:linkname must refer to declared function or variable
go/pkg/mod/golang.org/x/[email protected]/unix/zsyscall_darwin_amd64.go:121:3: too many errors

Setup golangci-lint

We can use the Github Action and inserts the errors right into the UI.

      - name: golangci-lint
        uses: golangci/golangci-lint-action@v2
        with:
          version: v1.31

Currently it can't be run because the code base has a mix of WASM/non-wasm code. I think we just need exclude the js code with build tags?

sean@SeanLaptop:~/go/src/github.com/maxmcd/webtty$ golangci-lint run
WARN [runner] Can't run linter goanalysis_metalinter: S1031: failed prerequisites: [([email protected]/maxmcd/webtty/web-client/src, [email protected]/maxmcd/webtty/web-client/src): analysis skipped: errors in package: [/home/sean/go/src/github.com/maxmcd/webtty/web-client/src/main.go:4:2: could not import syscall/js (-: build constraints exclude all Go files in /opt/go/src/syscall/js)]]
WARN [runner] Can't run linter unused: buildir: failed to load package : could not load export data: no export data for "syscall/js"
ERRO Running error: buildir: failed to load package : could not load export data: no export data for "syscall/js"

Beginner question?

I run webtty in two xterms, and they seem to connect but then I only get lines with:

inbound isControlling && a.isControlling == true

Maybe I am not using it right, but this was my first test :-)

Quitting with an unexpected error: "failed to parse IP address"

When pasting the answer from web, the process fail with the following message:

Quitting with an unexpected error: "failed to parse IP address"

passing the key as an argument in URL

As title. Instead of opening up https://maxmcd.github.io/webtty/ (the site below) and manually initializing the connection (copy-pasting the key/answer), I am considering an usage like passing the key directly in URL like https://maxmcd.github.io/webtty/index.html&key=33j2kxK3PadnEFo... to link to an already waiting on-way webtty server.

Once this function is ready, it can be integrated into some web service, in which a background thread opens up a webtty server, parses the key it outputs and generates the link with the key as the argument. The user can just click the link in the browser to seamlessly access to the terminal. I am doing this using gotty, but it is no longer being maintained while WebRTC looks more interesting.

This is not a feature request. Rather, I would like to contribute to this project by adding this feature, if you consider it useful. I was planning to finish this function first and discuss this feature directly in the PR thread, but it is not obvious to me how to host a local site like the site for development. I tried building the npm dependencies and used a static http server to host '/web-client/dist', but the basic function is missing: it just keeps telling me There was an error with the offer: <the key>...Try entering the message again: and loops forever. The key works with the site, so there must be something missing in my build. Any hints?

Google STUN server

Hello,

I noticed that webtty uses stun.l.google.com:19302 by default, it would be nice to be able to setup another STUN server without modifying the code directly, but with an option at runtime for example.

[Help Needed] Webtty vs SSH for IOT Nodes connected through a CG-NAT

Background

We are currently using a Reverse Port Forwarding setup. An SSH server is hosted on a cloud instance. The IOT node uses a 4G Cellular Grade NAT to connect to the internet.

This setup allows us to ssh into our IOT node without a public IP for each node.

Advantages

Webtty appears to be an attractive alternative to our current approach:

• No need to host and maintain a SSH server
• No need to create ssh keys and pass them around to SSH server for each IOT node
• Use a web interface to connect to IOT devices -> Easier for operations engineers
• Create short lived connections to IOT nodes with Connection keys that expire after a certain duration and close the Webrtc connection

Questions

• Is webrtc a reliable method to access an IOT node for maintenance purposes, a replacement for SSH?
• Is the use of webrtc to access shell on a remote IOT node secure?
• Is this a recommended use case for webtty?

Thanks for making this library open source!

Chinese with your README.md , if you like

Translation

https://github.com/chinanf-boy/webtty-zh

Issue with initial handshake

I've installed webtty on OSX 10.12.5, along with dependecies. From the go/bin folder, I'm running webtty -cmd -v, which gives me an offer message.

I paste the message into the https://maxmcd.github.io/webtty/ and get the answer, which I paste back into the host, which fails with this message:

Answer recieved, connecting...
Failed to push SCTP packet: Failed handling chunk: TODO Handle Init when in state CookieWait

If I run webtty -cmd -h -v, I get to the same point with this error on the host machine:

Answer recieved, connecting...
Failed to push SCTP packet: Failed handling chunk: TODO Handle Init when in state CookieWait
Terminal session started:
Quitting with an unexpected error: "exec: "-h": executable file not found in $PATH"

And the website disconnects.

When I try to connect two local terminal sessions, I get this error message on the host machine:

Failed to push SCTP packet: Failed handling chunk: TODO Handle Init when in state CookieWait
Terminal session started:
Quitting with an unexpected error: "exec: "-h": executable file not found in $PATH"

But the client terminal starts a terminal session, but without a console.

Any ideas what the problem might be?

Upgrade WASM code to Go 1.12+

$ npm run build

> [email protected] go-build
> mkdir -p ./dist/ && touch ./dist/foo && rm ./dist/* && GOOS=js GOARCH=wasm go build -o ./dist/main.wasm ./src

# github.com/maxmcd/webtty/web-client/src
src/main.go:61:28: undefined: js.NewCallback
src/main.go:62:28: undefined: js.NewCallback

Onmessage has not been set for Datachannel data 0 ERROR

often (every 2nd or 3rd try) i get the error that the Onmessage-event-handler is not set after successfully established connection:

...
Terminal session started:
Onmessage has not been set for Datachannel data 0
                                                  Onmessage has not been set for Datachannel data 0
                                                                                                    Onmessage has not been set for Datachannel data 0

the connection is successful because for every keypress on the host-side i get one "Onmessage has not been set for Datachannel data 0" error-message on the client side.

dont know, but maybe cause some of the function you are using from webrtc are deprecated? e.g. Onmessage (https://github.com/pions/webrtc/blob/0043a4bf9adfdf01f8ece009432384a621b56f2c/rtcdatachannel.go#L96) or rtcPeerConnection *RTCPeerConnection (https://github.com/pions/webrtc/blob/0043a4bf9adfdf01f8ece009432384a621b56f2c/rtcdatachannel.go#L107) 🤷‍♂️

prebuilt binaries for arm (raspberry and company)

First of all thank you for your work in this project and especially the thought of releasing the prebuilt binaries

I suppose you have or are using some kind of automated infrastructure or service to do this ( goreleaser ? github actions), so I think this request wouldn't be too much of an extra effort.

But it would be extremely usefull, for getting webtty on tiny less powerfull computers , SBC boards etc. Think of Raspberrry Pi and alike. It's not practical to download the entire Go chain infrastructure and build on them.

I also know it can be cumbersome to support "all" of arm architectures . Should it be arm5 or armv6 or ... ?

But I've seen from other (go) projects that do this, that usually all it takes is one single arm binary for not 64bit arm (raspberry 2 and zero ) and one for 64bit arm (aarch64 armv8, raspberry 4 ) . Go projects 99% of the time run wonderfully on all them.

So I would like to request if you could provide this.
If a "universal" not 64 bit binary not possible, then at least an armv7h binary for the Raspberry Pi 2.

pions/webrtc needs go version > 1.8

Hi, just got this message when doing go get -u github.com/maxmcd/webtty with go 1.8:

# github.com/pions/webrtc
.go/src/github.com/pions/webrtc/media.go:11: syntax error: unexpected = in type declaration

Tried again with go version 1.9.7 and it worked. I know it depends on pions/webrtc but maybe you could add a note in the README about the minimum required go version 🙂