Concepts

See also qtermy concepts.

buffer identifier

A one-byte number which identifies a buffer within a terminal. XTerm-style terminals have two buffers: a primary scrollback buffer (numbered 0), and an "alternate screen buffer" (numbered 1) with no scrollback. Full-screen text mode programs such as vim use the alternate screen buffer to avoid overwriting scrollback contents.

client identifier

A UUID generated by a TermySequence client to uniquely identify itself. This appears in the protocol handshake, in ANNOUNCE_CLIENT messages, and elsewhere in the TermySequence protocol. The method of generation is unspecified; version 4 (random) identifiers are acceptable.

character position

A logical character position within a row of terminal text. Each logical character may include multiple Unicode code points and may be single width or double width. The terminal's encoding determines the width of characters and how they combine.

CURSOR_MOVED state updates include both the x position and character position of the cursor. Double-width characters may cause these two values to differ. Also included in cursor state updates is the cursor sub-position, which is the number of combining characters received at the current position.

connection

A command directly executed by a server in order to establish a connection to another server. This is one method of performing connection chaining, the other being a connection through a terminal.

For the most part, connections are treated as terminals by the TermySequence protocol. Terminal identifiers and connection identifiers are grouped together by some messages such as REQUEST_DISCONNECT. qtermy follows this convention, displaying connections as "terminals" with fixed screen content.

connection chaining

A signature feature of the TermySequence protocol, connection chaining refers to the ability of each server to establish protocol connections to additional servers through its own terminals. From the perspective of the user, these "chained" servers and their terminals can be interacted with just as though they were directly connected. Traffic to and from each server is routed through intermediary servers as necessary, using each server's unique identifier as its address.

A chained connection can be made using any intermediary program that results in an instance of termy-server being run on another machine, as another user, or in a container. For example, ssh(1), sudo(8), and su(1) can all be used for this purpose (termy-server ships with wrappers for these particular programs). To see connection chaining in action, try running sudo -i termy-server from a terminal in qtermy.

In addition to connecting through terminals, termy-server can also execute intermediary programs directly. This is referred to in the protocol as a connection. Besides not using up a terminal, this makes it possible to use a faster 8-bit encoding. The termy-connect utility can be used to open a new connection in this manner.

connection identifier

See terminal identifier.

content identifier

An 8-byte unsigned number which identifies an inline content item. These are created by termy-download, termy-imgcat, and termy-imgls and reported to clients as regions with the Image region type. The content identifier is included in the region's attributes. It is used to download the content item via an IMAGE_CONTENT request or DOWNLOAD_IMAGE task.

region identifier

A 4-byte unsigned number which identifies a region. The number zero is an invalid identifier. The server generates identifiers for regions that it manages, such as job and annotation regions.

server identifier

A UUID generated by a TermySequence server to uniquely identify itself. This appears in the protocol handshake, in CLIENT_ANNOUNCE messages, and elsewhere in the TermySequence protocol.

To construct its identifier, termy-server must be provided with a unique machine ID for the local system. By default, termy-server attempts to determine this value using a platform-specific source such as /etc/machine-id. It's possible to explicitly set the local machine ID using a script. Refer to termy-server for more information.

The local machine ID is combined with the server's UID and standalone mode to produce the final identifier used by the server. This ensures that servers run as different users and in different modes of operation (transient and persistent) have different identifiers.

If termy-server cannot determine the local machine ID at all, it will randomly generate an identifier. This is undesirable because it's impossible for clients to track server settings for such a server.

server name

The name server attribute is intended to convey a second name string to supplement the server's hostname. The attribute monitor distributed with termy-server sets the server name to one of the server's IP addresses using a heuristic. Depending on the system, the attribute monitor may also report IP address changes as they occur (on Linux, netlink(7) is used for this purpose).

The server name may be customized to any desired value using a script. Refer to termy-monitor for more information.

server translations

The server has a small number of human-readable strings that can be translated. Translation files are text files stored at prefix/share/termy-server/i18n and named after their respective locale, for example fr.txt. Each line of the text file must contain a string identifier and translation separated by an equals (=) character with no spaces. See here for an example.

Note that in addition to the server's system locale, each terminal has its own independent Language setting that controls the translation of server strings printed to the terminal.

task

An exchange of messages between a client and server within the TermySequence protocol. Tasks are used to upload and download files, execute commands, forward ports, and more.

A task is initiated by a client, which assigns a task identifier to the task. Some tasks may prompt the user for information using question and answer messages. The task then proceeds to an exchange of input and output messages structured according to the rules of the specific task type. Tasks can be canceled and can time out or fail with an error. Tasks might cause throttle messages to be sent to the client if too much output data is buffered at an intermediate server. Tasks will be automatically canceled if the client disconnects before the task is complete.

task identifier

A UUID that uniquely identifies a task within the TermySequence protocol.

It is the responsibility of clients to generate these identifiers for tasks that they create. Version 4 (random) identifiers are recommended.

terminal identifier

A UUID that uniquely identifies a terminal or connection within the TermySequence protocol.

It is the responsibility of clients to generate these identifiers for terminals that they create. Version 4 (random) identifiers are recommended.

Connection identifiers are randomly generated by the server.