Skip to content

Feature/postmessage cb #1469

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Feature/postmessage cb #1469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
904d782
postMessageOrigin: implement parent.postMessage()
sven-ola Aug 31, 2025
63d9023
postMessageOrigin: add help to man page
sven-ola Aug 31, 2025
3da1a09
postMessageOrigin: compiled typescript to javascript
sven-ola Aug 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions html/src/components/terminal/xterm/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ export interface ClientOptions {
trzszDragInitTimeout: number;
unicodeVersion: string;
closeOnDisconnect: boolean;
postMessageOrigin?: string;
}

export interface FlowControl {
Expand Down Expand Up @@ -101,6 +102,7 @@ export class Xterm {
private reconnect = true;
private doReconnect = true;
private closeOnDisconnect = false;
private postMessageOrigin?: string;

private writeFunc = (data: ArrayBuffer) => this.writeData(new Uint8Array(data));

Expand Down Expand Up @@ -281,6 +283,10 @@ export class Xterm {
private onSocketClose(event: CloseEvent) {
console.log(`[ttyd] websocket connection closed with code: ${event.code}`);

if (this.postMessageOrigin) {
parent.postMessage('close_ttyd', this.postMessageOrigin!);
}

const { refreshToken, connect, doReconnect, overlayAddon } = this;
overlayAddon.showOverlay('Connection Closed');
this.dispose();
Expand Down Expand Up @@ -455,6 +461,11 @@ export class Xterm {
break;
}
break;
case 'postMessageOrigin':
if (!value || value === '') return;
console.log(`[ttyd] setting postMessage origin: ${value}`);
this.postMessageOrigin = value;
break;
default:
console.log(`[ttyd] option: ${key}=${JSON.stringify(value)}`);
if (terminal.options[key] instanceof Object) {
Expand Down
107 changes: 37 additions & 70 deletions man/ttyd.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Cross platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt/LEDE, Windows
.SH OPTIONS
.PP
-p, --port
Port to listen (default: 7681, use \fB\fC0\fR for random port)
Port to listen (default: 7681, use \fB0\fR for random port)

.PP
-i, --interface
Expand Down Expand Up @@ -162,46 +162,43 @@ Cross platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt/LEDE, Windows
.PP
ttyd has a mechanism to pass server side command-line arguments to the browser page which is called \fBclient options\fP:

.PP
.RS

.nf
.EX
-t, --client-option Send option to client (format: key=value), repeat to add more options

.fi
.RE
.EE

.SH Basic usage
.RS
.IP \(bu 2
\fB\fC-t rendererType=canvas\fR: use the \fB\fCcanvas\fR renderer for xterm.js (default: \fB\fCwebgl\fR)
\fB-t rendererType=canvas\fR: use the \fBcanvas\fR renderer for xterm.js (default: \fBwebgl\fR)
.IP \(bu 2
\fB\fC-t disableLeaveAlert=true\fR: disable the leave page alert
\fB-t disableLeaveAlert=true\fR: disable the leave page alert
.IP \(bu 2
\fB\fC-t disableResizeOverlay=true\fR: disable the terminal resize overlay
\fB-t disableResizeOverlay=true\fR: disable the terminal resize overlay
.IP \(bu 2
\fB\fC-t disableReconnect=true\fR: prevent the terminal from reconnecting on connection error/close
\fB-t disableReconnect=true\fR: prevent the terminal from reconnecting on connection error/close
.IP \(bu 2
\fB\fC-t enableZmodem=true\fR: enable ZMODEM
\fB-t enableZmodem=true\fR: enable ZMODEM
\[la]https://en.wikipedia.org/wiki/ZMODEM\[ra] / lrzsz
\[la]https://ohse.de/uwe/software/lrzsz.html\[ra] file transfer support
.IP \(bu 2
\fB\fC-t enableTrzsz=true\fR: enable trzsz
\fB-t enableTrzsz=true\fR: enable trzsz
\[la]https://trzsz.github.io\[ra] file transfer support
.IP \(bu 2
\fB\fC-t enableSixel=true\fR: enable Sixel
\fB-t enableSixel=true\fR: enable Sixel
\[la]https://en.wikipedia.org/wiki/Sixel\[ra] image output support (Usage
\[la]https://saitoha.github.io/libsixel/\[ra])
.IP \(bu 2
\fB\fC-t closeOnDisconnect=true\fR: close the terminal on disconnection, this will disable reconnect
\fB-t closeOnDisconnect=true\fR: close the terminal on disconnection, this will disable reconnect
.IP \(bu 2
\fB\fC-t titleFixed=hello\fR: set a fixed title for the browser window
\fB-t titleFixed=hello\fR: set a fixed title for the browser window
.IP \(bu 2
\fB\fC-t fontSize=20\fR: change the font size of the terminal
\fB-t fontSize=20\fR: change the font size of the terminal
.IP \(bu 2
\fB\fC-t unicodeVersion=11\fR: set xterm unicode support level (default: 11, use 6 to disable unicode addon)
\fB-t unicodeVersion=11\fR: set xterm unicode support level (default: 11, use 6 to disable unicode addon)
.IP \(bu 2
\fB\fC-t trzszDragInitTimeout=3000\fR: set the timeout in milliseconds for initializing drag and drop files to upload. (default: 3000)
\fB-t trzszDragInitTimeout=3000\fR: set the timeout in milliseconds for initializing drag and drop files to upload. (default: 3000)
.IP \(bu 2
\fB-t postMessageOrigin=http://url\fR: set origin for postMessage to parent window on socket close

.RE

Expand All @@ -212,50 +209,40 @@ You can use the client option to change all the settings of xterm defined in ITe

.RS
.IP \(bu 2
\fB\fC-t cursorStyle=bar\fR: set cursor style to \fB\fCbar\fR
\fB-t cursorStyle=bar\fR: set cursor style to \fBbar\fR
.IP \(bu 2
\fB\fC-t lineHeight=1.5\fR: set line-height to \fB\fC1.5\fR
\fB-t lineHeight=1.5\fR: set line-height to \fB1.5\fR
.IP \(bu 2
\fB\fC-t 'theme={"background": "green"}'\fR: set background color to \fB\fCgreen\fR
\fB-t 'theme={"background": "green"}'\fR: set background color to \fBgreen\fR

.RE

.PP
to try the example options above, run:

.PP
.RS

.nf
.EX
ttyd -t cursorStyle=bar -t lineHeight=1.5 -t 'theme={"background": "green"}' bash

.fi
.RE
.EE


.SH EXAMPLES
.PP
ttyd starts web server at port 7681 by default, you can use the -p option to change it, the command will be started with arguments as options. For example, run:

.PP
.RS

.nf
.EX
ttyd -p 8080 bash -x

.fi
.RE
.EE

.PP
Then open http://localhost:8080 with a browser, you will get a bash shell with debug mode enabled. More examples:

.RS
.IP \(bu 2
If you want to login with your system accounts on the web browser, run \fB\fCttyd login\fR\&.
If you want to login with your system accounts on the web browser, run \fBttyd login\fR\&.
.IP \(bu 2
You can even run a non-shell command like vim, try: \fB\fCttyd vim\fR, the web browser will show you a vim editor.
You can even run a non-shell command like vim, try: \fBttyd vim\fR, the web browser will show you a vim editor.
.IP \(bu 2
Sharing single process with multiple clients: \fB\fCttyd tmux new -A -s ttyd vim\fR, run \fB\fCtmux new -A -s ttyd\fR to connect to the tmux session from terminal.
Sharing single process with multiple clients: \fBttyd tmux new -A -s ttyd vim\fR, run \fBtmux new -A -s ttyd\fR to connect to the tmux session from terminal.

.RE

Expand All @@ -264,10 +251,7 @@ Sharing single process with multiple clients: \fB\fCttyd tmux new -A -s ttyd vim
.PP
Generate SSL CA and self signed server/client certificates:

.PP
.RS

.nf
.EX
# CA certificate (FQDN must be different from server/client)
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -subj "/C=CN/ST=GD/L=SZ/O=Acme, Inc./CN=Acme Root CA" -out ca.crt
Expand All @@ -281,36 +265,24 @@ openssl req -newkey rsa:2048 -nodes -keyout client.key -subj "/C=CN/ST=GD/L=SZ/O
openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt
openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12
openssl pkcs12 -in client.p12 -out client.pem -clcerts

.fi
.RE
.EE

.PP
Then start ttyd:

.PP
.RS

.nf
.EX
ttyd --ssl --ssl-cert server.crt --ssl-key server.key --ssl-ca ca.crt bash

.fi
.RE
.EE

.PP
You may want to test the client certificate verification with \fIcurl\fP(1):

.PP
.RS

.nf
.EX
curl --insecure --cert client.p12[:password] -v https://localhost:7681

.fi
.RE
.EE

.PP
If you don't want to enable client certificate verification, remove the \fB\fC--ssl-ca\fR option.
If you don't want to enable client certificate verification, remove the \fB--ssl-ca\fR option.


.SH Docker and ttyd
Expand All @@ -328,12 +300,9 @@ Creating new docker container for each client: ttyd docker run -it --rm ubuntu.

.SH Nginx reverse proxy
.PP
Sample config to proxy ttyd under the \fB\fC/ttyd\fR path:
Sample config to proxy ttyd under the \fB/ttyd\fR path:

.PP
.RS

.nf
.EX
location ~ ^/ttyd(.*)$ {
proxy_http_version 1.1;
proxy_set_header Host $host;
Expand All @@ -343,9 +312,7 @@ location ~ ^/ttyd(.*)$ {
proxy_set_header Connection "upgrade";
proxy_pass http://127.0.0.1:7681/$1;
}

.fi
.RE
.EE


.SH AUTHOR
Expand Down
1 change: 1 addition & 0 deletions man/ttyd.man.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ ttyd has a mechanism to pass server side command-line arguments to the browser p
- `-t fontSize=20`: change the font size of the terminal
- `-t unicodeVersion=11`: set xterm unicode support level (default: 11, use 6 to disable unicode addon)
- `-t trzszDragInitTimeout=3000`: set the timeout in milliseconds for initializing drag and drop files to upload. (default: 3000)
- `-t postMessageOrigin=http://url`: set origin for postMessage to parent window on socket close

## Advanced usage

Expand Down
Loading