Connection

Connection settings are named settings objects stored at $HOME/.config/qtermy/connections. Connections can be edited from the Connect menu or the Manage Connections window. The files can also be edited directly in a text editor, but note that qtermy does not monitor for external changes to settings files. Use the reload files button in the Manage Connections window to load external changes and new files without restarting the application.

A connection is simply a command that runs termy-server as another user, on a remote machine, or in a container. The command can be run by qtermy itself or by a local or remote server using the principle of connection chaining. Any password prompts printed by the command will be shown in the Connection Status dialog which allows responses to be typed in and sent back to the command. If the connection is successful, the connected server and any additional servers already connected to it will become known to qtermy, appear in the Terminals tool, and be available for creating new terminals and performing file operations. A connection made from one server to another is visible to all connected clients on the originating server, not just the client that initiated the connection.

Two reserved connections are created for the persistent user server and transient local server. These connections cannot be edited or removed. Connections can be created using the Connect menu, Manage Connections window, or NewConnection action. A connection can be named, in which case it is saved to file and can be reused, or anonymous, in which case it is run only once and not saved for further use. Named connections can be favorited in the Manage Connections window, which will cause them to appear in the Favorite Connections menu. The most recently favorited connections of each Type will be shown directly in the Connect menu itself.

Outside of qtermy, anonymous connections can be made directly from the command line using the termy-connect utility and the termy-ssh, termy-sudo, and termy-su convenience scripts. It's even possible to directly invoke a connection command from a termy-server terminal. Refer to connection chaining for more information.

Depending on the specific external command used to launch termy-server, the communication channel may or may not be 8-bit clean. For example, escape sequences such as SSH ~ escapes and machinectl ^] escapes render a communication channel 8-bit unclean (the SSH escape sequence can be disabled using a command line argument, but the machinectl escape sequence cannot). Furthermore, the external command may not work unless it is run within a pseudoterminal. Commands that collect passwords sometimes have this limitation. The UseRawProtocol and UseLocalPty settings are provided to configure the connection appropriately for these cases. Refer to Troubleshooting: Failed to Connect for further assistance in troubleshooting a connection that won't go through.

A Batch Connection can be used to run one or more saved connections in sequence. This allows connections to be quickly and easily opened to remote systems across multiple hops.

Tip

Open commonly used connections, including batch connections, in a single keystroke by making a key binding to to the OpenConnection action with your connection specified as the ConnName parameter. You won't miss typing in SSH commands from scratch.

Type

Type (enumeration)

Specifies the type of connection made by this connection object. This setting controls which icon is displayed for the connection, which New Connection Dialog is used to edit it, and where it appears in the Connect menu, if it is shown there.

Caution

This setting is purely cosmetic in nature and may not accurately reflect the connection's actual Command.

Server

LaunchFrom (string)

Specifies the UUID of the server from which the connection's Command will be run. If this setting is empty, the command is run directly by qtermy as a child process.

The list of servers is in the dropdown for this setting is populated from the list of known servers. A server must have been previously seen by qtermy to appear in the list. To work around this limitation, a server settings file can be manually installed and then loaded using the reload files button in the Manage Servers window (assuming that its UUID is known). Refer to Server for more information.

Note

The server specified here must be connected when the connection is opened. If this is not the case, the connection will fail.

Batch connections provide a way to open multiple connections in sequence.

Connection

Command (stringlist)

The command to run. This is a list of strings consisting of an executable name and argument vector (including argument zero).

The command must result in an instance of termy-server being run or a connection to an existing termy-server's Unix domain socket being made, such that the standard input and output of the command are forwarded to that server or socket. Based on the characteristics of the connection provided by the command, set UseRawProtocol and UseLocalPty as appropriate.

Commands entered into the text field will be split on whitespace and the first word will be used as both the executable to run and argument zero of the argument vector, unless the first word ends with a separate argument in square brackets. In this case, the portion before the square brackets is used as the executable name and the portion within the square brackets is used as argument zero.

For more control over the argument vector, click the Advanced button to bring up a command editor dialog. The dialog displays the executable name and argument vector separately and supports arguments containing whitespace.

Important

Shell constructs such as quoting and variable expansion should not be used since the command may not be run by a shell. Use a wrapper script if this is required.

Directory (string)

The directory which the Command is run from. If unspecified, the command will be started in the user's HOME directory.

Environment (stringlist)

Environment variable rules used to set and clear environment variables before running the Command.

UseRawProtocol (boolean)

If enabled, the 8-bit "raw" binary encoding of the TermySequence protocol will be used on the connection. Do not enable this setting unless the communication channel created by the Command is known to be fully 8-bit clean. A connection is not clean if any of the following are true after initial setup (such as password prompts) has been performed and termy-server is running:

• The communication channel has any in-band signaling or escape sequences such as SSH ~ escapes and machinectl ^] escapes. It may be possible to disable escape sequences using a command option such as the -e argument to ssh(1).
• The communication channel expects data in a particular text encoding such as 7-bit ASCII or UTF-8.
• Error messages or other strings are printed into the communication channel. It may be possible to disable these using a "quiet" command option such as the -q argument to ssh(1).

If disabled, the 7-bit Base64 encoding of the TermySequence protocol will be used on the connection. It is slower but more robust against unclean communication channels.

UseLocalPty (boolean)

If enabled, the Command will be run inside a pseudoterminal. Some programs that display password prompts require this. The pseudoterminal will be set up in "raw" mode to make it 8-bit clean. It may be possible to remove the need for a local pseudoterminal using a command option such as the -S argument to sudo(8).

KeepaliveTime (integer)

The time between keepalive messages on the connection in milliseconds. If either side of the connection does not receive a keepalive message from the other side within twice the specified time period, the connection will be automatically closed. Use this setting to prevent "frozen" servers and terminals caused by a lost network connection, terminated process, or sleep/hibernate event. If set to zero, no keepalive messages will be sent.

Note

The keepalive messages configured by this setting are part of the TermySequence protocol and are sent at the application layer. This setting does not control transport layer keepalive probes specified by tcp(7).

Batch

Contents (stringlist)

A list of connection names to be invoked in sequence. Only applicable to batch connections.