1termy-server(1) General Commands Manual termy-server(1)
2
6 termy-server - TermySequence terminal multiplexer server
7
10 termy-server [options]
11
14 termy-server is a multiplexing terminal emulator server implementing
15 the TermySequence protocol. The emulator aims for XTerm compatibility
16 and supports modern terminal extensions such as 256-color text, mouse
17 tracking, shell integration, and inline image display. In addition, the
18 TermySequence protocol provides many features beyond standard terminal
19 emulation, including flexible, efficient connectivity between servers,
20 file monitoring and transfer, and multi-user terminal sharing and col‐
21 laboration.
22 Note: termy-server does not provide a text-based user interface in the
24 manner of tmux(1) or screen(1). A separate client program such as
25 qtermy(1) must be used to interact with the terminals themselves. The
26 client program will typically launch the server automatically, making
27 it unnecessary to run termy-server directly in most cases. The intent
28 is to separate the display and user interface components from the
29 server, allowing a single server implementation to support a wide vari‐
30 ety of clients, including clients such as qtermy(1) specifically built
31 for graphical windowing systems.
32 By default, termy-server forks into the background, services standard
34 input, and listens on a private, per-user Unix-domain socket for addi‐
35 tional connections. If the socket is found to be already bound to
36 another termy-server instance, standard input will be forwarded to the
37 existing server (using file descriptor passing when possible to avoid
38 copying overhead). This makes it possible to run a server using e.g.
39 ssh(1) or sudo(8), gaining access to an existing multiplexer running on
40 another host or as another user (see termy-connect(1)). When forward‐
41 ing standard input, the server changes its name to termy-forwrd.
42 The command line options to termy-server are used to control the life‐
44 cycle of the server. The default behavior described above can be modi‐
45 fied to support private, standalone servers and socket-only daemon
46 servers, including socket-activated servers suitable for use with sys‐
47 temd(1) per-user instances. In all cases, the server exits on receipt
48 of SIGTERM, SIGINT, or SIGHUP, or when all clients have disconnected
49 and all terminals have closed.
50 Each termy-server instance forks a companion process, termy-monitor(1),
52 to collect system-specific information such as the hostname and IP
53 address. Three additional customizable programs: monitor-script, attr-
54 script, and id-script are also optionally read by termy-server to over‐
55 ride the default monitor process, provide additional system-specific
56 information, and to determine the UUID of the local machine, respec‐
57 tively (see FILES below). The system-specific information consists of
58 arbitrary UTF-8 key-value pairs which can be used to customize terminal
59 appearance within supporting TermySequence clients such as qtermy(1).
60
63 --nofork
64 Do not fork off a daemon process after startup. Note that even
65 when forking, if standard input is being serviced, the parent
66 process will remain running after the fork as long as standard
67 input is active.
68 --nostdin
71 Do not treat standard input as a client connection; accept
72 client connections on the per-user local socket only. If another
73 termy-server instance is already listening on the socket, exit
74 immediately.
75 --activated
78 Listen on a local socket passed in via systemd socket activa‐
79 tion. Implies --nofork, --nostdin, and --rundir %t/termy-server.
80 Won't work unless termy-server was compiled with systemd sup‐
81 port.
82 --nolisten
85 Do not listen on a per-user local socket for additional client
86 connections; service standard input only. Note that a connection
87 will still be made to the socket to determine if another termy-
88 server instance is already running, and if so, standard input
89 will be forwarded to it (see --standalone). Implies --nofork.
90 --standalone
93 Service standard input without attempting to either listen on or
94 connect to the per-user local socket. The server (and all termi‐
95 nals) will exit after standard input is closed. Implies
96 --nofork.
97 --client
100 Attempt to connect to an existing termy-server instance over the
101 per-user local socket and hand off standard input for servicing.
102 If no existing instance is listening, exit immediately.
103 -t,--rundir dir
106 Use runtime directory dir. It will be created if necessary, but
107 its parent directory must exist. The specifiers %t and %U, if
108 present, are expanded to $XDG_RUNTIME_DIR and the user UID
109 respectively. The default location is /tmp/termy-server%U unless
110 --activated is set, in which case this option is ignored. See
111 NOTES below for more information.
112 --nogit
115 Disable monitoring for and reporting of git-specific file
116 attributes and branch information. Only applicable if termy-
117 server was compiled with libgit2 support.
118 --nofdpurge
121 Don't look for and close leaked file descriptors on startup.
122 This is useful when debugging the server with tools such as val‐
123 grind.
124 --help Print basic help
127 --version
130 Print version information
131 --man Attempt to show this man page
134 --about
137 Print license information and disclaimer of warranty
138
141 $XDG_CONFIG_HOME/termy-server/id-script
142 /etc/termy-server/id-script
143 /usr/lib/termy-server/id-script
144 Programs executed by termy-server to determine the UUID of the local
146 machine. The program should print the UUID on standard output. By
147 default, /etc/machine-id is used; the id-script programs can be used as
148 an override or replacement for that file. One or the other must be
149 present; the TermySequence protocol requires each machine to have a
150 unique identifier.
151 $XDG_CONFIG_HOME/termy-server/attr-script
153 /etc/termy-server/attr-script
154 Programs executed by termy-server to set system-specific UTF-8 key-
156 value pairs reported to clients. The program should print lines of the
157 form key=value and must exit quickly. Refer to termy-monitor(1) for
158 more information. These scripts are optional and are not required to be
159 present.
160 $XDG_CONFIG_HOME/termy-server/monitor-script
162 /etc/termy-server/monitor-script
163 Programs executed by termy-server to set system-specific UTF-8 key-
165 value pairs reported to clients. The program should print lines of the
166 form key=value and may run as long as necessary, however it must exit
167 on receipt of SIGTERM or when its standard input is closed. By default
168 termy-monitor(1) is used for this purpose; the monitor-script programs
169 can be used as an override or replacement for this program. These
170 scripts are optional and are not required to be present.
171 termy-server runs the scripts on startup, and re-runs the attribute and
173 monitor scripts on receipt of SIGUSR1.
174
177 termy-server is not intended to be run setuid or setgid, and will exit
178 on startup if it detects this condition.
179 When attempting to connect to an existing server, the following loca‐
181 tions are searched for the per-user local socket in this order:
182 %t/termy-server (only if systemd support is enabled)
184 /run/user/%U/termy-server (only if systemd support is enabled)
185 /tmp/termy-server%U
186 The specifiers %t and %U are expanded to $XDG_RUNTIME_DIR and the user
188 UID respectively.
189 When listening, the per-user local socket and PID file are placed under
191 %t/termy-server if --activated is set. Otherwise, /tmp/termy-server%U
192 is used unless changed using the --rundir option.
193 The server verifies that the runtime directory is owned by the user and
195 has mode 0700. When making connections over the per-user local socket,
196 the SO_PASSCREDS socket option is used to verify that the peer has the
197 same UID. Refer to socket(7) and unix(7) for more information.
198
201 termy-monitor(1), termy-connect(1), termy-ssh(1), termy-su(1), termy-
202 sudo(1)
203 TermySequence - https://termysequence.io
204TermySequence™ March 2018 termy-server(1)