ptyctl

systemd

ptyctl

List, monitor and hang up pseudo TTYs registered with the pseudo TTY broker

ptyctl

OPTIONS

COMMAND

NAME

Description

ptyctl may be used to introspect and control the pseudo TTY allocations registered with the pseudo TTY broker, systemd-ptybrokerd.service(8). The broker keeps the frontend (i.e. the master) side of registered pseudo TTYs open, while the payload — a service, a container, a virtual machine console, or similar — runs connected to the backend (i.e. the slave) side. ptyctl permits listing these pseudo TTYs, interactively connecting to them, and hanging them up.

Pseudo TTYs are registered with the broker for example via --console=broker of systemd-pty-forward(1), systemd-nspawn(1) and systemd-vmspawn(1), or via StandardOutput=broker in service units, see systemd.exec(5).

Commands

The following commands are understood:

list
List the pseudo TTYs currently registered with the broker, showing their name, description, log tag, frontend and backend types, and backend TTY path. This command is the default if no command is specified.

monitor <NAME>
Connect interactively to the pseudo TTY registered under the specified name: its output is forwarded to the local terminal, and local input is forwarded back to it. To disconnect, press Ctrl+] three times within one second. Disconnecting only ends the monitor connection, the pseudo TTY itself remains registered with the broker and the payload continues to run.

hangup <NAME>…
Hang up the pseudo TTYs registered under the specified names. This executes the equivalent of vhangup(2) on the pseudo TTY, disconnecting the session running on its backend side.

Options

The following options are understood:

--system; --user
Selects whether to talk to the system-wide instance or the per-user instance of systemd-ptybrokerd.service(8). Defaults to --system.

--background=COLOR
Change the terminal background color to the specified ANSI color while monitoring a pseudo TTY. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as 40, 41, …, 47, 48;2;…, 48;5;…. See ANSI Escape Code (Wikipedia) for details. Only has an effect on the monitor command.

Example: --background=44 for a blue background.

--title=TITLE
Change the terminal title to the specified string while monitoring a pseudo TTY. Only has an effect on the monitor command.

--quiet; -q
Suppresses additional informational output while running.

Exit status

On success, 0 is returned, a non-zero failure code otherwise.