yudai / gotty

Share your terminal as a web application

GoTTY - Share your terminal as a web application

GoTTY is a simple command line tool that turns your CLI tools into web applications.

Installation

Download the latest stable binary file from the Releases page. Note that the release marked Pre-release is built for testing purpose, which can include unstable or breaking changes. Download a release marked Latest release for a stabale build.

(Files named with darwin_amd64 are for Mac OS X users)

Homebrew Installation

You can install GoTTY with Homebrew as well.

$ brew install yudai/gotty/gotty

go get Installation (Development)

If you have a Go language environment, you can install GoTTY with the go get command. However, this command builds a binary file from the latest master branch, which can include unstable or breaking changes. GoTTY requires go1.9 or later.

$ go get github.com/yudai/gotty

Usage

Usage: gotty [options] <command> [<arguments...>]

Run gotty with your preferred command as its arguments (e.g. gotty top).

By default, GoTTY starts a web server at port 8080. Open the URL on your web browser and you can see the running command as if it were running on your terminal.

Options

--address value, -a value     IP address to listen (default: "0.0.0.0") [$GOTTY_ADDRESS]
--port value, -p value        Port number to liten (default: "8080") [$GOTTY_PORT]
--permit-write, -w            Permit clients to write to the TTY (BE CAREFUL) [$GOTTY_PERMIT_WRITE]
--credential value, -c value  Credential for Basic Authentication (ex: user:pass, default disabled) [$GOTTY_CREDENTIAL]
--random-url, -r              Add a random string to the URL [$GOTTY_RANDOM_URL]
--random-url-length value     Random URL length (default: 8) [$GOTTY_RANDOM_URL_LENGTH]
--tls, -t                     Enable TLS/SSL [$GOTTY_TLS]
--tls-crt value               TLS/SSL certificate file path (default: "~/.gotty.crt") [$GOTTY_TLS_CRT]
--tls-key value               TLS/SSL key file path (default: "~/.gotty.key") [$GOTTY_TLS_KEY]
--tls-ca-crt value            TLS/SSL CA certificate file for client certifications (default: "~/.gotty.ca.crt") [$GOTTY_TLS_CA_CRT]
--index value                 Custom index.html file [$GOTTY_INDEX]
--title-format value          Title format of browser window (default: "{{ .command }}@{{ .hostname }}") [$GOTTY_TITLE_FORMAT]
--reconnect                   Enable reconnection [$GOTTY_RECONNECT]
--reconnect-time value        Time to reconnect (default: 10) [$GOTTY_RECONNECT_TIME]
--max-connection value        Maximum connection to gotty (default: 0) [$GOTTY_MAX_CONNECTION]
--once                        Accept only one client and exit on disconnection [$GOTTY_ONCE]
--timeout value               Timeout seconds for waiting a client(0 to disable) (default: 0) [$GOTTY_TIMEOUT]
--permit-arguments            Permit clients to send command line arguments in URL (e.g. http://example.com:8080/?arg=AAA&arg=BBB) [$GOTTY_PERMIT_ARGUMENTS]
--width value                 Static width of the screen, 0(default) means dynamically resize (default: 0) [$GOTTY_WIDTH]
--height value                Static height of the screen, 0(default) means dynamically resize (default: 0) [$GOTTY_HEIGHT]
--ws-origin value             A regular expression that matches origin URLs to be accepted by WebSocket. No cross origin requests are acceptable by default [$GOTTY_WS_ORIGIN]
--term value                  Terminal name to use on the browser, one of xterm or hterm. (default: "xterm") [$GOTTY_TERM]
--close-signal value          Signal sent to the command process when gotty close it (default: SIGHUP) (default: 1) [$GOTTY_CLOSE_SIGNAL]
--close-timeout value         Time in seconds to force kill process after client is disconnected (default: -1) (default: -1) [$GOTTY_CLOSE_TIMEOUT]
--config value                Config file path (default: "~/.gotty") [$GOTTY_CONFIG]
--version, -v                 print the version

Config File

You can customize default options and your terminal (hterm) by providing a config file to the gotty command. GoTTY loads a profile file at ~/.gotty by default when it exists.

// Listen at port 9000 by default
port = "9000"

// Enable TSL/SSL by default
enable_tls = true

// hterm preferences
// Smaller font and a little bit bluer background color
preferences {
    font_size = 5
    background_color = "rgb(16, 16, 32)"
}

See the .gotty file in this repository for the list of configuration options.

Security Options

By default, GoTTY doesn't allow clients to send any keystrokes or commands except terminal window resizing. When you want to permit clients to write input to the TTY, add the -w option. However, accepting input from remote clients is dangerous for most commands. When you need interaction with the TTY for some reasons, consider starting GoTTY with tmux or GNU Screen and run your command on it (see "Sharing with Multiple Clients" section for detail).

To restrict client access, you can use the -c option to enable the basic authentication. With this option, clients need to input the specified username and password to connect to the GoTTY server. Note that the credentical will be transmitted between the server and clients in plain text. For more strict authentication, consider the SSL/TLS client certificate authentication described below.

The -r option is a little bit casualer way to restrict access. With this option, GoTTY generates a random URL so that only people who know the URL can get access to the server.

All traffic between the server and clients are NOT encrypted by default. When you send secret information through GoTTY, we strongly recommend you use the -t option which enables TLS/SSL on the session. By default, GoTTY loads the crt and key files placed at ~/.gotty.crt and ~/.gotty.key. You can overwrite these file paths with the --tls-crt and --tls-key options. When you need to generate a self-signed certification file, you can use the openssl command.

openssl req -x509 -nodes -days 9999 -newkey rsa:2048 -keyout ~/.gotty.key -out ~/.gotty.crt

(NOTE: For Safari uses, see how to enable self-signed certificates for WebSockets when use self-signed certificates)

For additional security, you can use the SSL/TLS client certificate authentication by providing a CA certificate file to the --tls-ca-crt option (this option requires the -t or --tls to be set). This option requires all clients to send valid client certificates that are signed by the specified certification authority.

Sharing with Multiple Clients

GoTTY starts a new process with the given command when a new client connects to the server. This means users cannot share a single terminal with others by default. However, you can use terminal multiplexers for sharing a single process with multiple clients.

For example, you can start a new tmux session named gotty with top command by the command below.

$ gotty tmux new -A -s gotty top

This command doesn't allow clients to send keystrokes, however, you can attach the session from your local terminal and run operations like switching the mode of the top command. To connect to the tmux session from your terminal, you can use following command.

$ tmux new -A -s gotty

By using terminal multiplexers, you can have the control of your terminal and allow clients to just see your screen.

Quick Sharing on tmux

To share your current session with others by a shortcut key, you can add a line like below to your .tmux.conf.

# Start GoTTY in a new window with C-t
bind-key C-t new-window "gotty tmux attach -t `tmux display -p '#S'`"

Playing with Docker

When you want to create a jailed environment for each client, you can use Docker containers like following:

$ gotty -w docker run -it --rm busybox

Development

You can build a binary using the following commands. Windows is not supported now. go1.9 is required.

# Install tools
go get github.com/jteeuwen/go-bindata/...
go get github.com/tools/godep

# Build
make

To build the frontend part (JS files and other static files), you need npm.

Architecture

GoTTY uses xterm.js and hterm to run a JavaScript based terminal on web browsers. GoTTY itself provides a websocket server that simply relays output from the TTY to clients and receives input from clients and forwards it to the TTY. This hterm + websocket idea is inspired by Wetty.

Alternatives

Command line client

• gotty-client: If you want to connect to GoTTY server from your terminal

Terminal/SSH on Web Browsers

• Secure Shell (Chrome App): If you are a chrome user and need a "real" SSH client on your web browser, perhaps the Secure Shell app is what you want
• Wetty: Node based web terminal (SSH/login)
• ttyd: C port of GoTTY with CJK and IME support

Terminal Sharing

• tmate: Forked-Tmux based Terminal-Terminal sharing
• termshare: Terminal-Terminal sharing through a HTTP server
• tmux: Tmux itself also supports TTY sharing through SSH)

License

The MIT License

gotty's Issues

Once and reconnect can not work together

Gotty is very awesome.

When I set ' --once' , the console can not reconnect.
So I cannot use gotty in a unstable network with once feature.

Thanks .

Run as a daemon process

Adding a "-d" flag or something similar to run gotty as a daemon process will prevent taking up the terminal.

Exit gotty server when connection is closed?

Hi, my use case is I'm trying to provide an in-browser SSH client, however I'll be spawning up the gotty process when the request comes in and I want to kill it when the user exits ssh. What I'm using is:

gotty -w ssh [email protected]

The problem currently I'm seeing is, when I go to browser and exit the ssh prompt (with exit command for instance), the gotty process stays alive and keeps accepting connections and new connections cause ssh command above to be restarted.

What I do need instead is, gotty server to quit when user quits by exiting the process so that I can garbage collect resources and next time user visits my service (say, http://example.com/ssh/[email protected]) I will spawn another gotty server.

@yudai does it sound like a good proposal to have an argument that makes the gotty server quit once the executed process quits (rather than staying alive and re-execing the specified command when a new request comes in)?

Missing the hterm.js in resources/ folder.

May be you use go-bindata, even through this program can work, but hterm.js still not found.

OS X 10.10.5, Safari 8.0.8 cannot handle basic authentication

OS X 10.10.5, Safari 8.0.8 issue: "failed: Unexpected response code: 401"

Work very well in OS X 10.10.5, Firefox 40.0.3

Use standard VGA colors or allow for custom palette

https://en.wikipedia.org/wiki/ANSI_escape_code#Colors

As I mentioned in another issue, I'm using GoTTY as a bridge for my telnet BBS, but the colors are a bit off for VGA textmode artwork.

https://oddnetwork.org/bbs/

Awesome work, anyway! I really appreciate the app.

Change "Connection Closed" notice to be a translucent banner

So that it's more noticeable.

Windows 7 installation issue

Hi, i am trying to install this app in Windows, but getting the following error :

D:\projects>go get github.com/yudai/gotty
# github.com/kr/pty
D:\go_workspace\src\github.com\kr\pty\ioctl.go:6: undefined: syscall.SYS_IOCTL
D:\go_workspace\src\github.com\kr\pty\ioctl.go:6: not enough arguments in call to syscall.Syscall
D:\go_workspace\src\github.com\kr\pty\run.go:21: unknown syscall.SysProcAttr field 'Setctty' in struct literal
D:\go_workspace\src\github.com\kr\pty\run.go:21: unknown syscall.SysProcAttr field 'Setsid' in struct literal
D:\go_workspace\src\github.com\kr\pty\util.go:26: undefined: syscall.SYS_IOCTL
D:\go_workspace\src\github.com\kr\pty\util.go:28: undefined: syscall.TIOCGWINSZ
D:\go_workspace\src\github.com\kr\pty\util.go:30: not enough arguments in call to syscall.Syscall

Is this a Windows specific issue?

HTTP Basic Authentication support

Duplicating the command for each client

I've ran into this while showing this tool to my collegue. When ever I would run the command kitchen converge The first few people to connect are actually good, but then at some point every refresh/new connection cause the command the be ran gain.

EDIT: it seems to stop at 2... The first ps is at start with me watching, then the second one is after my collegue joined.

Incomplete unicode support

Unicode symbols are not interpreted correctly during input from the browser, while terminal-to-browser utf output works fine.

1st cmd - terminal input
3rd cmd - browser input
osx yosemite, darwin_amd64 gotty pre-release

Defunkt processes after each connect

Getting defunkt processes after each connect with GoTTY. They seem to linger on after each spawn.

(PS: GoTTY is awesome btw!)

32bit version

Hi,

Is it possible to have a 32 bit binary version in Release archive ?

Thanks

Slice bounds out of range in App.generateHandler…→UTF8Reader.Read

Saw a crash when a second client connected to gotty into a tmux session holding htop (i.e., ran via gotty tmux attach -t gotty to show it to a coworker, 'cause this is pretty awesome).

$ tmux new-session -s gotty htop
…
$ gotty tmux attach -t gotty
2015/08/17 07:59:02 Sever is running at :8080, command: tmux attach -t gotty
2015/08/17 07:59:04 New client connected: 10.0.3.89:58751
2015/08/17 07:59:26 New client connected: 10.0.3.211:63808
panic: runtime error: slice bounds out of range

goroutine 5 [running]:
github.com/yudai/utf8reader.(*UTF8Reader).Read(0xc82003ef58, 0xc82021c800, 0x400, 0x400, 0x400, 0x0, 0x0)
    GOPATH/src/github.com/yudai/utf8reader/utf8reader.go:47 +0x2ca
github.com/yudai/gotty/app.(*App).generateHandler.func1.1(0xc8201e1e30, 0xc820032018, 0xc820112460, 0xc8201101e0)
    GOPATH/src/github.com/yudai/gotty/app/app.go:89 +0x1f3
created by github.com/yudai/gotty/app.(*App).generateHandler.func1
    GOPATH/src/github.com/yudai/gotty/app/app.go:103 +0x5d3

… other goroutines behaving normally …

Unfortunately haven't been able to reproduce it, so possibly a fluke. Figured I'd open an issue and if I come up on other details I'll amend the issue.

Cannot set Preference color-palette-overrides

When setting 'color-palette-overrides' I get the following error in the javascript debug window (firefox)

[15:34:58.042] "Preference color-palette-overrides is not an array or object: {'0':'#073642','1':'#dc322f','2':'#859900','3':'#b58900','4':'#268bd2','5':'#d33682','6':'#2aa198','7':'#eee8d5','8':'#002b36','9':'#cb4b16','10':'#586e75','11':'#657b83','12':'#839496','13':'#6c71c4','14':'#93a1a1','15':'#fdf6e3'}"

In my .gotty file I intered

color_palette_overrides = "{'0':'#073642','1':'#dc322f','2':'#859900','3':'#b58900','4':'#268bd2','5':'#d33682','6':'#2aa198','7':'#eee8d5','8':'#002b36','9':'#cb4b16','10':'#586e75','11':'#657b83','12':'#839496','13':'#6c71c4','14':'#93a1a1','15':'#fdf6e3'}"

Within the Preference object.

Add Linux_armhf release

Could it be possible to add Linux ARMHF (Raspberry Pi) releases ?

Thanks !

Terminal to Terminal connection

For environments where people use w3m and cannot run hterm,

Terminal A: gotty -w tmux new -A -s foo
Then,
Terminal B gotty -x

It would be great if terminal B sends a broadcast packet and automatically discovers terminal A.

When running "clear" and another client attaches, the screen refreshes

To reproduce:

$ gotty tmux new -A -s gotty top

Connect via tmux:

tmux att -t gotty

• Connect to localhost:8080 to view the terminal in a browser
• Inside tmux, create a new pane and type something
• Now type clear to clear the terminal buffer
• Connect with another client
• -> The contents which were just cleared reappear

settings from .gotty not loading

mbp ~ → gotty -v
gotty version 0.0.9
mbp ~ → cat .gotty
// Listen at port 9000 by default
port = "9000"

// Enable TSL/SSL by default
//enable_tls = true

// hterm preferences
// Smaller font and a little bit bluer background color
preferences {
    font_size = 5,
    background_color = "rgb(16, 16, 32)"
}
mbp ~ → gotty bash
2015/09/01 21:31:19 Loading config file at: /Users/paul/.gotty
2015/09/01 21:31:19 Server is starting with command: bash
2015/09/01 21:31:19 URL: http://[::1]:8080/
2015/09/01 21:31:19 URL: http://127.0.0.1:8080/
2015/09/01 21:31:19 URL: http://[fe80::1]:8080/
2015/09/01 21:31:19 URL: http://[fe80::7a31:c1ff:fed1:584]:8080/
2015/09/01 21:31:19 URL: http://192.168.88.157:8080/
2015/09/01 21:31:19 URL: http://192.168.99.1:8080/
2015/09/01 21:31:19 URL: http://192.168.50.1:8080/
2015/09/01 21:31:19 URL: http://172.16.82.1:8080/
2015/09/01 21:31:19 URL: http://172.16.0.1:8080/

OS X 10.10.5 issue: "crypto/tls: failed to parse certificate PEM data"

gotty installed by instruction by the brew.
keys generated by instruction.

at start gotty logs this issue:
crypto/tls: failed to parse certificate PEM data

Proxy through Apache for SSL and Authentication

Has anyone managed to successfully get Gotty working through Apache?

I can't resolve the issue of WebSocket not initializing:

Request URL:wss://.../console/ws
Request Method:GET
Status Code:403 Forbidden

The Gotty log:

2015/08/18 12:46:08 New client connected: 127.0.0.1:33020
2015/08/18 12:46:08 Failed to upgrade connection

The Apache Configuration:

<VirtualHost *:443>
SSLEngine on
SSLProtocol all -SSLv2
SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM

SSLCertificateFile ...
SSLCertificateKeyFile ...
SSLCertificateChainFile ...

ServerName ...

ProxyPass /console/ws ws://localhost:8075/ws
ProxyPassReverse /console/ws ws://localhost:8075/ws
ProxyPass /console http://localhost:8075
ProxyPassReverse /console http://localhost:8075

<Location /console>
AuthType Basic
AuthName "Console"
AuthUserFile /etc/apache2/console.passwd
Require valid-user
Order allow,deny
Allow from all
</Location>

Any suggestions are welcomed, I tried everything I could think of.

Midnight Commander ... frozen on Qnap with Gotty

Thanks for this apps, run fine on Qnap NAS QPKG is available here

http://forum.qnap.com/viewtopic.php?f=320&t=113304

but i wonder why Midnight commander stay frozen.. not sure how to debug

Publish on homebrew

Please make this tool installable via Homebrew. 👍

Browsers can't open IPv6 addrs

➜  ~  gotty -w top
2015/08/23 12:20:01 Server is starting with command: top
2015/08/23 12:20:01 URL: http://::1:8080/
2015/08/23 12:20:01 URL: http://127.0.0.1:8080/
2015/08/23 12:20:01 URL: http://fe80::1:8080/
2015/08/23 12:20:01 URL: http://fe80::a65e:60ff:fecc:5cc7:8080/
2015/08/23 12:20:01 URL: http://192.168.0.113:8080/
2015/08/23 12:20:01 URL: http://fe80::6048:20ff:fea9:ec6f:8080/
2015/08/23 12:20:01 URL: http://192.168.99.1:8080/

From what observe on Chrome and Safari on OS X is browsers can't open addrs like http://::1:8080/ or http://fe80::a65e:60ff:fecc:5cc7:8080/ at all. Maybe the program should just print IPv4 ones?

Alt key is being mapped to meta key

The alt key ("option key") on OS X gets mapped to the meta key, making it impossible to write e.g. "@" (on my keyboard layout "@" is alt+2) and a range of other characters (©, £, $, ∞, §, |, [, ], etc.).

Windows binary/release

1. Will this ever work with Windows?
2. If it can, is windows support on the dev path?
3. What could a "regular Joe" user do to use this on windows right now? Using it in docker is the simplest option?

PS: I'm excited 😄

Can not use IME to input CJK

gotty -w vim

Embedded terminal multiplexer for screencast

The ability for web clients to send input to the gotty'd process is awesome, but it would also be excellent to allow the user who is hosting the gotty process to use STDIN to "screencast" to consumers.

Ideal flow:

gotty nano /tmp/some/file

Gotty starts, and the tty used to start gotty acts exactly as if the command had been run without gotty. The user can "screencast" their input and results to web consumers - without web consumers necessarily being able to control the process.

Consider change gotty name, there is another gotty and older software

Hello,

I was searching for this handy software and this first link http://gotty.io/ appeared.

Could you consider to change name to avoid future confusion like this one? http://gotty.io is older than this project.

Thanks.

Support for URL links

It would be nice if there are URLs in the screen the gotty / JS could convert them into links which will open into new window.

The code should be aware if the URL continues into the next line like (typical situation in chat window):

SomeNick: Check this out: http://www.foo.com/bar/dir/something/inde
x.php that's so cool!
OtherNick: yes!

possilbity to set authentification for user uid 0

Hi Yudai,

can it be possible to set authentification using the uid 0 user for example.

this could allow Qnap users to log with the admin user (no root on qnap) set on their box, instead to set a custom user/password

I think it could be a good enhancement for Gotty.

Cloudflare blocking Websockets - "Failed to upgrade connection"

2015/08/19 20:56:32 New client connected: <my ip>:26736
2015/08/19 20:56:32 Failed to upgrade connection

Getting this error sometimes, only on Chrome. Firefox runs it well.
Client shows only a blank page.
Yesterday I had tried it out already and everything was fine.

Feature: Disable resizing

It would be nice if you could disable the resizing feature. Overlapping areas could be accessed via a scrollbar inside the browser.

Ability to deliver parameters and client info via URL/POST/cookie or similar

I would be nice if it's possible to deliver parameters or information about the client to the command to be executed when client connects to gotty.

Example1:
gotty /opt/cmd
http://hostname:8080/?arg1=foo&arg2=bar => gotty will execute /opt/cmd arg1=foo arg2=bar

In terms of security reasons it would be reasonable if it's possible to limit what arguments should be delivered and what data could be into them (only digits / only A-Z)?

Example2:
gotty /opt/cmd %CLIENT_IP_ADDRESS%
192.168.1.10 connects to http://hostname:8080/ => gotty will execute /opt/cmd 192.168.1.10

Tittle lost on update

The tittle tag losses it's initial value when contents are updated.

ARM V5 request

Hi Master Yudai

the actual binary release is for ARM6, possible to have ARM5 version, i am sure some qnap user will love your application

thanks a lot ,

Unprintable Characters disconnect Gotty

When doing dumb stuff like cat /dev/random or cat on binaries which yield unprintable characters (and may screw up a terminal under "normal" circumstances ) lead to a disconnection. This is especially bad when byobu (tmux wrapper) runs in the background, which makes reconnection impossible ;-).

I don't know if this is fixable, but I thought worth mentioning.

Custom Fonts

It would be nice to be able to use custom fonts. I added this with the raw one, it was pretty straight forward if I remember correctly.

Release does not include files needed for building.

Running "make" against the provided makefile immediately fails with:

make: *** No rule to make target `libapps/hterm/js/*.js', needed by `bindata/hterm.js'.  Stop.

libapps/ is an empty directory.

No rule to make target `libapps/hterm/js/*.js'

when i compiled source code,found code err

mkdir bindata
make: *** No rule to make target `libapps/hterm/js/*.js', needed by `bindata/hterm.js'.  Stop.

feature request: copy and paste

Copy and paste wold be an awesome improvement!

Thank you!

Allow clients to specify commnd

I know, it's dangerous enough.

Option 1

Allow send only arguments like run gotty --permit-arguments tailf then, access http://server.exmple.com:8080/%2Fvar%2Flog%2Fsyslog (/var/log/syslog).
(Need to take care of shell meta characters not to permit using pipe and redirects)

Option 2

Freedom mode like gotty --freedom then, access http://server.example.com:8080/tailf+%2Fvar%2Flog%2Fsyslog.

404 Not Found

gotty --random-url --permit-write top --addr 127.0.0.1

When I go to the page. I get 404 not found.

Surface IP addresses of connected clients

It would be helpful if the IP addresses of the clients could be part of the logging. Working on an educational application for shared terminal window and it would help with debugging.

Random URL generation

URL generation for something like an authentication alternative.

Add an option to generate URLs like:

https://host:8080/nairj3gnw5ja39r23

SSL Support

Default SSL support by the server must be required.

Set the HTML title to something more descriptive than just "GoTTY"

Suggestion: "GoTTY - #{command} (#{hostname})"

Most secure jailed environment?

Very nice project!

I was planning to try it, and my first idea has been to use it inside Docker, for security reasons.

You suggest to launch docker via gotty, but I think this is a vulnerability.

As discussed in the past on docker security, it might be possible to crash the docker container, allowing to execute commands on the host.

Wouldn't it be better to launch docker, then run gotty INSIDE docker?

Feature: Livereload

It would be nice if gotty would tell the webbrowser to automatically reload the page if an old session was finished/killed and a new one was started on the same port. Should be easy to implement on the client side.

Keep up the good work! This package is a big one for me! 👍

once option doesn't kill child processes

For me, if I run gotty --once -w vim then connect in the browser, then close the browser tab, I find that gotty is still running.