1termy-server(1)             General Commands Manual            termy-server(1)
2
3
4

NAME

6       termy-server - TermySequence terminal multiplexer server
7
8

SYNOPSIS

10       termy-server [options]
11
12

DESCRIPTION

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
23       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
33       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
43       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
51       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
61

OPTIONS

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
69
70       --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
76
77       --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
83
84       --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
91
92       --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
98
99       --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
104
105       -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
113
114       --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
119
120       --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
125
126       --help Print basic help
127
128
129       --version
130              Print version information
131
132
133       --man  Attempt to show this man page
134
135
136       --about
137              Print license information and disclaimer of warranty
138
139

FILES

141       $XDG_CONFIG_HOME/termy-server/id-script
142       /etc/termy-server/id-script
143       /usr/lib/termy-server/id-script
144
145       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
152       $XDG_CONFIG_HOME/termy-server/attr-script
153       /etc/termy-server/attr-script
154
155       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
161       $XDG_CONFIG_HOME/termy-server/monitor-script
162       /etc/termy-server/monitor-script
163
164       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
172       termy-server runs the scripts on startup, and re-runs the attribute and
173       monitor scripts on receipt of SIGUSR1.
174
175

NOTES

177       termy-server  is not intended to be run setuid or setgid, and will exit
178       on startup if it detects this condition.
179
180       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
183       %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
187       The  specifiers %t and %U are expanded to $XDG_RUNTIME_DIR and the user
188       UID respectively.
189
190       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
194       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
199

SEE ALSO

201       termy-monitor(1),  termy-connect(1),  termy-ssh(1), termy-su(1), termy-
202       sudo(1)
203       TermySequence - https://termysequence.io
204
205
206
207TermySequence™                    March 2018                   termy-server(1)
Impressum