Remoting over ssh ¶

The command syntax:

domterm [browser-specifier] [user]@host [command]

runs domterm [command] as user on the remote server host, using ssh to connect. However, if the command creates a new session (or attaches to an existing session on host), then the session will be displayed in a local window, as specified by the optional browser-specifier. For example. if the latter is --tab, a new tab will be created in the current window.

Note each sub-window is independent and can be local or connected to different remote server.

This mechanism does not require any superuser access, network ports/servers, or credential/security management beyond those used by standard ssh.

Here is a summary of how it works.

Specifing the remote destination ¶

The general syntax is:

domterm [options] remote-destination [remote-options] [command args]

where a remote-destination is [user]@host[:port] . Here host is the name or IP address of the remote computer, as processed by the ssh command. The user is the user name on the remote host, by default the same as the current local user name. The port is the protocol port which the remote ssh server listens to, by default 22.

You can also use URL syntax ssh://[user@]host[:port], which is converted to the former syntax.

Local vs remote state ¶

When you create a remote connection, there are distinct servers running on the local machine vs the remote machine. Suppose you have a local window and you create a remote session as a sub-window:

domterm --below @192.168.1.55

If you run the domterm status you see what the local server knows about:

Window 1:  qtwebengine: 5.6.1, chrome: 45.0.2454.101
  session#1: pid: 5287, tty: /dev/pts/2
  session#2: ssh to remote @192.168.1.55#1

Session 1 is a local session, while session 2 is a remote session. Note that what the local server thinks of as session 2 is a proxy for session 1 on the remote server: You can also see the status of the remote server using domterm @192.168.1.55 status.

Connection 1 via ssh from 192.168.1.58
  session#1: pid: 6464, tty: /dev/pts/1

Attaching and detaching ¶

It you detach from a remote session, the session will be detached on the remote end, while the local server will remove all state from its end.

Later you can connect to a detached session number on host:

domterm @host attach :number

Note that the number is the session number as managed by the remote server. This may be different from the local session number that the session had before you detached it. To find out which sessions have been detached on host you can ask the remote server for its status, including detached sessions:

domterm @host status

Slow connections ¶

Normally terminal interaction sends each character (keystroke) individually to the remove server, and the process on the remote server will respond with terminal escape sequence to update the display to match what you typed. This called echo. This can be annoying if the round-trip time is noticable.

To alleviate this, DomTerm predicts echo from certain key-presses, based on what it expects the remote server to do. This is done for regular characters (which are inserted), left and right arrow (move caret), Backspace (delete previous character), and Delete (delete following character). This predication is shown with a gray background to indicate it is tentative. After a while (controllable by the predicted-input-timeout setting), if the predicated echo does not happen, DomTerm will undo its predication. You should set predicted-input-timeout to be longer than the typical round-trip time; the default is 0.4 seconds.

For example suppose you type A, then B, the C. DomTerm tentatively inserts ABC. Then it receives echo to insert AB. First, DomTerm removes the prediction, and performs whatever updates have been requested. Then DomTerm compared the resulting line with what it predicted. It sees that the current display corresponds to echo of A, and B, but not C. It therefore updates the display to show a predicted tentative C.

Another way to deal with a slow connection is to switch to line-editing mode. Then you can compose an input line (or even multiple input lines) completely locally, before you type Enter to send the line(s) to the server. You can switch back and forth as much as it is convenient, even in the middle of a line. If you have a partial input line (by default shown with a green border), and then switch to regular character mode, the partial line is converted to a predicated insertion and then sent to the server (which will normally echo it).

Dealing with connection loss ¶

When connecting over a network, there is always the issue of how to deal with temporary or permanent connection failure. Also, what happens if your local laoptop dies (runs out of power or is re-booted) or you start a session using your work computer, and want to check on the sesssion using your home computer?

DomTerm offers these strategies:

• In many cases, after the network freezes or you sleep either the local or remote computer, reconnecting happens smoothly without problems. The local display state will persist in the local browser process.
• Explicit detaching and re-attaching. If you have warning you will need to disconnect, especially if you may have to re-connect from a different computer or network, it is best to explicitly detach the session. The local display state will be downloaded to and saved on the remote server. The remote server and user process will remain alive, but no resources will be needed for a browser process or local server state until you re-attach.
• Background headless browser. If you are concerned you be disconnected without warning and/or have to re-connect from another computer, you can create a duplicate headless window running on the remote server. The session will be attached to two connections: The headless window on the remote server, and a regular display window on the local computer. The connections will be synchronized (as long as both are alive and connected), and both will have the display state. Even if the local computer dies, if you attach to the server, it can request the needed display state from the headless window.

  It is planned (but not yet implemented) to have an option to automatically create the background headless window.

Sharing sessions (experimental) ¶

Multiple people can attach to the same remote session, assuming they all have ssh login access to the remote computer.

For security reasons, it is probably best to create a separate user identity for shared sessions. Using Unix user groups may also be practical but hasn’t been explored. It would also be useful to be able to grant some users read-only access and some modification acess (to allow user input). This should be dynamically switchable a session owner.

In addtion to security, there are practical issues to resolve, such as what happens when different users have their windows set to different widths.

Build domterm for a server ¶

If the domterm command is not installed on your remote server, build DomTerm as shown (on a compatible platform). (The --with-libwebsockets option cause that library to be linked statically, which is recommended if they might not be installed on the remote server.)

./configure --prefix=/tmp/DT --without-java --with-libwebsockets=lws_dir
make install
cd /tmp
zip -r DT.zip DT
scp DT.zip remote_host:/tmp

On the remote_host, where remote_dir is some directory you have write access to (could be the home directory):

cd remote_dir
unzip /tmp/DT.zip

After that you should be able to connect from your local machine using the command.remote-domterm setting:

domterm command.remote-domterm=remote_dir/DT/bin/domterm remote_user@remote_host [command]