# user-space virtual terminals

As an augmentation to, or a complete replacement for, kernel virtual terminals, this package also allows you to set up user-space virtual terminals. A user-space virtual terminal comprises at minimum four things:

- a pseudo-terminal

- a TUI login service that has the pseudo-terminal as its controlling terminal

- a terminal emulator process, that conects the pseudo-terminal to a display buffer and an input FIFO

- one or more realizer processes, that connect the display buffer and input FIFO to real I/O devices of some kind

To them can optionally be added:

- a front-end processor process for running a set of input methods

- a multiplexor process for mapping one display buffer and input FIFO onto many

In a plain system, the TUI login service, the terminal emulator process, and the realizer process all run as ordinary services. This package comes with service bundles for running three user-space virtual terminal emulators (`vc1`, `vc2`, and `vc3`), multiplexed onto a single realizer (`head0`) through a multiplexor and an input method.

In a containerized system, the TUI login services and the terminal emulation services run in the container. The realizer and console multiplexor services, conversely, run outwith the container. One simply directs the (external) console multiplexor service to include the contained user-space virtual terminal devices, alongside any that it already has. With the `console-multiplexor@head0` service bundle that comes in this package, simply symbolically link the contained user-space virtual terminal directories into the multiplexor's service directory before starting it. This is nothing more than an instance of the general-case procedure for adding another user-space virtual terminal to a multiplexor service.

>     ln -s /var/container/run/dev/vc1 /var/service-bundles/services/console-multiplexor@head0/service/vc9
>     ln -s /var/container/run/dev/vc2 /var/service-bundles/services/console-multiplexor@head0/service/vc10
>     ln -s /var/container/run/dev/vc3 /var/service-bundles/services/console-multiplexor@head0/service/vc11

## terminal emulator services

Each user-space virtual terminal has one service, running `console-terminal-emulator`. This duplicates the function of the old-style kernel terminal emulator code, but as an application-mode process outwith the kernel.

It is explicitly not an emulator for any model of real terminal. Its function is to correctly cope with the outputs of programs that are using (according to operating system) the `linux`, `cons25`, `pcvt25`, `pccon`, or `teken` entries in the termcap/terminfo databases; those being the entries that are used for kernel terminal emulators. In other words, one should be able to switch from a kernel virtual terminal to a user-space virtual terminal without changing the terminal type used in the ttylogin service.

It is the terminal emulator service that creates the `tty` device file, and so the terminal emulator service must start before any TUI login service for that terminal does. A `console-terminal-emulator@1.service` must be ordered before its corresponding `ttylogin@1.service` in the startup sequence with an appropriate symbolic link in the latter's service bundle's `after/` directory, for example.

Terminal emulator services do not require superuser privileges at any stage; and for best security should be run under the aegis of an unprivileged account dedicated to the service(s).

## multiplexors

A multiplexor service runs `console-multiplexor`. This provides a simple screen-switching service that presents one virtual terminal display buffer and input FIFO that is switched amongst one or more other terminal display buffers and input FIFOs. This again duplicates the function of the old-style kernel terminal emulator code, but as an application-mode process outwith the kernel.

Realizers recognize special input gestures (usually keyboard chords, specified in a keyboard map of some kind) for switching screens, which they turn into distinct screen switch messages that are sent to the input FIFO. That input FIFO is the one provided by the mutiplexor, which strips these messages out of the input stream (so that the actual terminal emulators "downstream" never see them) and acts upon them, switching amongst the downstream virtual terminals as commanded.

The `console-multiplexor-control` command, also available under the name `chvt`, generates the same messages. A user with sufficient access to the input FIFO, the security concerns of which you can find discussed in the user manual, can programmatically switch a multiplexor between multiple inputs.

Unlike the kernel virtual terminal system, this system is not limited to just this kind of simple multiplexor. One could create more complex multiplexors to provide, say, a multiple pane interface that displayed multiple downstream virtual terminals simultaneously. Because the system is composable, this does not require any change to the terminal emulator programs.

## input method front-end processors

An input method front-end processor service runs `console-input-method`. This overlays a pre-editing user interface on top of a virtual terminal, presenting itself as another virtual terminal with its own display buffer and input FIFO.

When inactive, it operates in simple pass-through mode. Active, it injects its user interface near to the underlying display buffer's cursor and intercepts the input messages originating from a realizer, not passing them "downstream" but rather passing downstream the input that the user has pre-edited in its user interface.

Front-end processing is driven by files containing data tables, determining how character composition is actually performed by the pre-editing. The front-end processor can be loaded with several data tables, switching between them on the fly, allowing input to be composed in several CJKV and romaji (i.e. American/European) modes. The data files themselves are in a format that has been around for years, and that is common to several input method softwares: `CIN`. It is a fairly simple exercise to add and to use one's own data files for custom input methods; and a fairly sizeable library of existing methods already exists in the world at large.

The `console-input-method-control` command generates various special input method key messages. A user with sufficient access to the input FIFO, the security concerns of which you can find discussed in the user manual, can programmatically switch input method modes and toggle the input method on and off.

## realizers

The relationship between realizers and terminals is many-to-many. A realizer may be a simple realizer, that handles just one user-space virtual terminal. Or it may be a complex realizer that handles multiple user-space virtual terminals, multiplexing their displays onto its output device, and allowing the user to switch amongst virtual terminals with a hotkey sequence, or a mouse action of some kind. One can also attach multiple display-only realizers to a single user-space virtual terminal with no ill-effects. All realizers will operate concurrently.

The lifetimes of realizers do not affect the lifetimes of the associated virtual terminals. One can detach all realizers from a user-space virtual terminal, and it will continue operating, its output stored in its display buffer file, unaffected. This differentiates user-space virtual terminals from, say, X Window System terminal programs, which signal hangup to the session leader programs running in the terminal when rendering is commanded to close its window.

Realizers are configured by setting up symbolic links, files, and directories (c.f. `user-vt-realizer-configuration`) in their working directories. For realizers run as services, the working directories are the service directories and this configuration sits alongside the other service configuration files. See user-space virtual terminal configuration for an explanation of configuration policies and the various ways in which one can approach configuring realizers.

Realizers only require access to the files of the user-space virtual terminals that they are attached to, and to the various I/O devices that they are realizing the virtual terminal with. The exact security model depends from the kind of realizer, and there are many possible kinds; one could have:

- `console-fb-realizer` — a realizer that uses a framebuffer device, realizing the display of one user-space virtual terminal. This realizer needs additional privileged access to the device file, in order to open it at startup, but needs no more privileges than that.

- `console-ugen-hid-realizer` — a realizer that uses a generic USB human input device, realizing input to one user-space virtual terminal. This realizer needs additional privileged access to the device files (there being one per interface), in order to open them at startup, but needs no more privileges than that.

- `console-wscons-realizer` — a realizer that uses the display and input of a wscons device, realizing the display of one user-space virtual terminal. This realizer needs additional privileged access to the device file, in order to open it at startup, but needs no more privileges than that.

- `console-termio-realizer` — a realizer that uses straight terminal I/O, hardwiring DEC VT, SCO Console, ISO, and ECMA control sequences, to render one user-space virtual terminal on the terminal that the realizer itself has inherited as its standard I/O. This realizer needs no additional privileged access to anything apart from the files of the user-space virtual terminal.

- a realizer that realizes one user-space virtual terminal on a Braille device. This realizer initially needs additional privileged access to the Braille device file, in order to open it, but can drop privileges afterwards.

- `console-ncurses-realizer` — a realizer that uses wide character ncurses (ncursesw) to render one user-space virtual terminal on the terminal that the realizer itself is attached to. This realizer needs no additional privileged access to anything apart from the files of the user-space virtual terminal.

- a realizer that realizes multiple user-space virtual terminals using X Window System windows, and allowing one to switch amongst them using hotkeys and mouse actions. This realizer initially needs no additional privileged access.