Troubleshooting: Failed to Connect

A TermySequence connection can fail to complete for a number of reasons. If you are still stuck after trying the solutions below, see Getting Help.

Server Not Installed

A TermySequence connection requires termy-server to be installed on the target machine and available to the target user. Fortunately, the server is written in C++ and has almost no dependencies, making it easy to build and install on a variety of systems.

Before building the server from source, check if it is available via the target machine's package manager. Refer to Getting Started for more information.

If it's not possible to install termy-server on the target machine, TermySequence connections cannot be used to access it. Connect to the machine by running a normal SSH command, container entry command, etc. from a terminal.

Server Not on Path

PATH problems are a common source of failed connections. The connections created using qtermy's New Connection Dialogs have a Command that simply runs "termy-server". This means that the termy-server executable must be on the target user's PATH on the target machine.

One way to fix the problem is to simply edit the offending connection from the Manage Connections window and change the Command to specify an absolute path to the termy-server executable.

Another way to fix the problem is to ensure that the user's PATH contains the directory where termy-server is installed. The way to accomplish this varies from shell to shell but usually involves setting the PATH environment variable from startup script such as .bashrc. Of course, this assumes that the program run from the connection's command either launches a shell or searches a configurable path itself. If this is not the case, it will be necessary to specify an absolute path to the termy-server executable or to create a wrapper script that runs termy-server and run the wrapper script from connection's command.

The behavior of ssh(1) and bash(1) with regard to PATH merits further discussion. When SSH is given an explicit command to run, it does so from a non-interactive, non-login shell. In the case of bash, this means that the target user's .profile and .bash_profile, which are only sourced from login shells, will not be sourced. On the other hand, the target user's .bashrc, which is normally sourced only from interactive shells, will be sourced (this is a special case for "network connections" only). Thus, PATH should be set from .bashrc, but there is another wrinkle: some startup scripts contain logic such as the following which checks for an interactive shell and exits the script early:

# If not running interactively, don't do anything
[ -z "$PS1" ] && return

PATH modifications made from .bashrc must happen before a check such as the one above in order to be honored by the (non-interactive) shell run from SSH. For more information about all of this, refer to this fine StackOverflow question and answer. For shells other than bash, check the shell's documentation and take note of the above when setting PATH. Some experimentation might be required.

Local Pseudoterminal

Making a connection to any server except a local server involves running termy-server as another user or on a remote machine. This in turn means that password prompts are likely to be displayed by the program run from the connection's command.

qtermy will display prompts and other strings printed by the program in a Connection Status dialog. User responses will be sent back to the program on its standard input. However, some programs such as ssh(1) refuse to read passwords from standard input unless it is a pseudoterminal. For such programs, make sure that the Connection/UseLocalPty setting is enabled.

The New Connection Dialogs may not pick the correct UseLocalPty setting for your system. Edit the offending connection from the Manage Connections window to change the setting.

On the other hand, some programs may not work when run inside a local pseudoterminal. This is because they configure the pseudoterminal in "cooked" mode using termios(3) settings, which in turn makes the communication channel unclean for 8-bit traffic (see the next section). To fix this, disable the local pseudoterminal if possible, otherwise disable the UseRawProtocol connection setting.

Protocol Encoding

The 8-bit "raw" encoding of the TermySequence protocol requires a communication channel that is fully 8-bit clean. Whether a communication channel is 8-bit clean or not depends on the program run from the connection's command. For connections that are not 8-bit clean, the 7-bit Base64 encoding of the TermySequence protocol must be used instead. It is slower but more robust against unclean communication channels.

The Connection/UseRawProtocol setting determines which encoding is used on the connection. Refer to that setting's documentation and the discussion at the top of Connection for more information about communication channels and 8-bit cleanliness. Make sure that the connection's Command includes any switches necessary to enable clean operation, if applicable.

The New Connection Dialogs may not pick the correct UseRawProtocol setting for your system. Edit the offending connection from the Manage Connections window to change the setting.

It's important to note that even the 7-bit Base64 encoding of the TermySequence protocol can be disrupted by human-readable strings printed into the connection channel. This can occur as a result of program error messages or by system-wide notifications printed into a local or remote pseudoterminal. Use mesg(1) to disable wall(1) notifications to your terminals. Make sure that the connection's Command includes any switches necessary to enable quiet operation, if applicable. Disable local and remote pseudoterminals entirely if possible.