1CONSOLE(1) conserver CONSOLE(1)
2
6 console - console server client program
7
9 console [generic-args] [-aAfFsS] [-e esc] console
10 console [generic-args] [-iIuwWx] [console]
11 console [generic-args] [-hPqQrRV] [-[bB] message] [-d [user][@console]]
12 [-t [user][@console] message] [-[zZ] cmd]
13 generic-args: [-7DEknUv] [-c cred] [-C config] [-M master] [-p port]
15 [-l user]
16
18 Console is used to manipulate console terminals remotely or to poll
19 running conserver(8) daemons for status information.
20 In the first form above, console asks the user's password before grant‐
22 ing interactive access to a console (on a non-trusted system), since
23 such a session may provide single-user access. If the server's auto‐
24 completion feature is enabled, only as much of the console name as is
25 required to identify it uniquely to the server is required.
26 For non-interactive options, console outputs only the requested infor‐
28 mation and exits.
29 Console knows only of a primary conserver host (see the -M option be‐
31 low), to which it initially connects. In a multi-server environment,
32 the primary server may refer the client to a different server handling
33 the requested console, or it will provide a list of all servers if re‐
34 quired (as when console is invoked with the -r option). Console then
35 opens connections to the appropriate server(s). It is not necessary
36 for the user of console to know which server manages which consoles, as
37 long as console knows a valid primary server and all available consoles
38 are listed in the primary server's configuration file.
39
41 Options may be given as separate arguments (e.g., -v -w) or clustered
42 (e.g., -vw). Options and their arguments may be separated by optional
43 white space. Option arguments containing spaces or other characters
44 special to the shell must be quoted.
45 -7 Strip the high bit off of all data received, whether from
47 user input or from the server, before any processing occurs.
48 Disallows escape sequence characters with the high bit set.
49 -a Access a console with a two-way (read-write) connection
51 (this is the default). The connection is dropped to spy
52 mode if someone else is attached read-write.
53 -bmessage Broadcast a message to all users connected to each server.
55 -Bmessage Same as -b but just send a message to users on the primary
57 server.
58 -ccred Load an SSL certificate and key from the PEM encoded file
60 cred.
61 -Cconfig Use the per-user configuration file config.
63 -d Disconnect the users specified by user@console. You may
65 specify the target as user (disconnect the user, regardless
66 of what console they are attached to), @console (disconnect
67 all users attached to console), or user@console (disconnect
68 the user attached to console).
69 -D Enable debugging output.
71 -eesc Set the initial two-character escape sequence to those rep‐
73 resented by esc. Any of the forms output by cat(1)'s -v op‐
74 tion are accepted. The default value is ``^Ec''.
75 -E If encryption has been built into the code (--with-openssl),
77 encrypted client connections are, by default, a requirement.
78 This option disables any attempt at creating an encrypted
79 connection. If you'd like to use encrypted connections when
80 your server supports it, but fallback to non-encrypted oth‐
81 erwise, the -U option is what you want.
82 -f Same as -a except it will force any existing connection into
84 spy mode.
85 -h Display a brief help message.
87 -i Display status information in a machine-parseable format
89 (see below for the details).
90 -I Same as -i but just acts on the primary server.
92 -k Abort the connection if the console is not in the `up' state
94 immediately upon connecting.
95 -luser Set the login name used for authentication to user. By de‐
97 fault, console uses $USER if its uid matches the user's real
98 uid, or $LOGNAME if its uid matches the user's real uid, or
99 else the name associated with the user's real uid.
100 -Mmaster The console client program polls master as the primary
102 server, rather than the default set at compile time (typi‐
103 cally ``console''). The default master may be changed at
104 compile time using the --with-master option. If --with-uds
105 is used to enable Unix domain sockets, however, this option
106 points console to the directory which holds those sockets.
107 The default master directory (``/tmp/conserver'') may be
108 changed at compile time using the --with-uds option.
109 -n Do not read the system-wide configuration file.
111 -pport Set the port to connect to. This may be either a port num‐
113 ber or a service name. The default port may be changed at
114 compile time using the --with-port option. If the --with-
115 uds option was used, this option is ignored.
116 -P Display the pid of the master daemon process on each server.
118 -q The console client connects to each server to request that
120 the server daemon quit (shut down). The root password of
121 the host(s) running conserver is required unless the local
122 host is listed as ``trusted'' in the conserver.cf file; in
123 that case, just press <return>.
124 -Q Same as -q but just acts on the primary server.
126 -r Display daemon versions. The console client connects to
128 each server to request its version information.
129 -R Same as -r but just acts on the primary server.
131 -s Request a read-only (spy mode) connection. In this mode all
133 the escape sequences (below) work, or report errors, but all
134 other keyboard input is discarded.
135 -t Send a text message to user@console. You may specify the
137 target as user (send to user, regardless of what console
138 they are attached to), @console (send to all users attached
139 to console), or user@console (send to user attached to con‐
140 sole).
141 -u Show a list of all consoles with status (`up', `down', or
143 `init') and attached users (user@host if attached read-
144 write, `<spies>' if only users in spy mode, or `<none>').
145 -U If encryption has been built into the code (--with-openssl),
147 encrypted client connections are, by default, a requirement.
148 This option allows the client to attempt an encrypted con‐
149 nection but fall back to a non-encrypted connection if the
150 server doesn't support encryption. If the encryption hand‐
151 shake is failing, disabling encryption on the client with
152 the -E option is probably what you want.
153 -v Be more verbose when building the connection(s). Use this
155 option in combination with any of `show' options (below) for
156 added benefit.
157 -V Output the version and settings of the console client pro‐
159 gram and then exit.
160 -w Show a list of all who are currently connected to consoles,
162 including the hostnames where the console connections origi‐
163 nate and the idle times. This is useful to see if anybody
164 is actively using the console system if it becomes necessary
165 to shut down conserver.
166 -W Same as -w but just acts on the primary server.
168 -x Show a list of consoles and devices.
170 -zcmd Sends a command (cmd) to each server and displays the re‐
172 sult. The valid commands are:
173 bringup Try to connect all consoles marked as down (this
175 is equivalent to sending the server a SIGUSR1)
176 SIGUSR1 Same as bringup
177 help Displays the help message
178 pid Returns the pid of the server (this is equiva‐
179 lent to -P)
180 quit Instructs the server to shut down (this is
181 equivalent to -q or sending the server a
182 SIGTERM)
183 SIGTERM Same as quit
184 reconfig Instructs the server to reload the configuration
185 file, then perform the actions of reopen (this
186 is equivalent to sending the server a SIGHUP)
187 SIGHUP Same as reconfig
188 reopen Instructs the server to reopen all logfiles,
189 then perform the actions of bringup (this is
190 equivalent to sending the server a SIGUSR2)
191 SIGUSR2 Same as reopen
192 version Returns the version of the server (this is
193 equivalent to -V)
194 -Zcmd Same as -z but just sends cmd to the primary server.
196 The -A, -F, or -S options have the same effect as their lower-case
198 variants. In addition, they each request the last 20 lines of the con‐
199 sole output after making the connection (as if ``^Ecr'' were typed).
200 The -i, -u, -w, and -x options can be given a console name, which will
202 limit their output to that console.
203 The -i option outputs status information regarding each console in 15
205 colon-separated fields.
206 name The name of the console.
208 hostname,pid,socket
210 The hostname, pid, and socket number of the child process manag‐
211 ing the console.
212 type The type of console. Values will be a `/' for a local device,
214 `|' for a command, `!' for a remote port, `%' for a Unix domain
215 socket, and `#' for a noop console.
216 console-details
218 The details regarding the console. The values here (all comma-
219 separated) depend on the type of the console. Local devices
220 will have values of the device file, baud rate/parity, and file
221 descriptor for the device. Commands will have values of the
222 command, the command's pid, the pseudo-tty, and file descriptor
223 for the pseudo-tty. Remote ports will have values of the remote
224 hostname, remote port number, ``raw'' or ``telnet'' protocol,
225 and file descriptor for the socket connection. Unix domain
226 sockets will have the path to the socket and the file descriptor
227 for the socket connection. Noop consoles will have nothing.
228 users-list
230 The details of each user connected to the console. The details
231 for each user are an `@' separated list of `w', `r', or `s' (for
232 read-write, read-only, or suspended), username, hostname the
233 user is on, the user's idle time, and (for `r' and `s' users
234 only) ``rw'' or ``ro'' (if the user wants read-write mode or
235 not). Each user bundle is separated by commas.
236 state The state of the console. Values with either be ``up'',
238 ``down'', or ``init''.
239 perm This value will either be ``rw'' or ``ro''. It will only be
241 ``ro'' if the console is a local device (`/' type) and the per‐
242 missions are such that the server can open the file for read,
243 but not write.
244 logfile-details
246 The details regarding the logging for the console. The comma-
247 separated values will be the logfile, ``log'' or ``nolog'' (if
248 logging is on or not - toggled via ``^EcL''), ``act'' or
249 ``noact'' (if activity logging is enabled or not - the `a' time‐
250 stamp option), the timestamp interval, and the file descriptor
251 of the logfile.
252 break The default break sequence used for the console.
254 reup If the console is currently down and the automatic reconnection
256 code is at work, it will have the value of ``autoup'', otherwise
257 it will be ``noautoup''.
258 aliases
260 The console aliases are presented in a comma-separated list.
261 options
263 The active options for the console are presented in a comma-sep‐
264 arated list.
265 initcmd
267 The initcmd configuration option for the console.
268 idletimeout
270 The idletimeout configuration option for the console.
271 idlestring
273 The idlestring configuration option for the console.
274
276 Console reads configuration information from the system-wide configura‐
277 tion file (console.cf), then the per-user configuration file (.consol‐
278 erc), and then applies command-line arguments. Each configuration lo‐
279 cation can override the previous. The same happens when parsing an in‐
280 dividual file - the later entries always override the earlier entries.
281 Because of that, you should put ``global'' defaults first and more spe‐
282 cific defaults second.
283 The configuration file is read using the same parser as con‐
285 server.cf(5), and you should check that manpage for parser details.
286 Console recognizes the following configuration blocks.
287 config hostname|ipaddr
289 Define a configuration block for the client host named hostname
290 or using the address ipaddr. If the value of ``*'' is used, the
291 configuration block will be applied to all client hosts.
292 escape esc
294 Set the escape sequence (see the -e command-line flag).
295 master master
297 Set the default master to master (see the -M command-line
298 flag).
299 playback num|""
301 Override the playback length for the p escape command to
302 num lines (if the server supports it). Using the special
303 value of ``0'' will cause the client to use the number of
304 lines of the current terminal (if that can be deter‐
305 mined). If the null string (``""'') is used, the play‐
306 back length will not be overridden.
307 port port
309 Set the default port to port (see the -p command-line
310 flag).
311 replay num|""
313 Override the replay length for the r escape command to
314 num lines (if the server supports it). Using the special
315 value of ``0'' will cause the client to use the number of
316 lines of the current terminal (if that can be deter‐
317 mined). If the null string (``""'') is used, the replay
318 length will not be overridden.
319 sslcacertificatefile filename
321 Load the valid CA certificates for the SSL connection
322 from the PEM encoded file.
323 sslcacertificatepath directory
325 Load the valid CA certificates for the SSL connection
326 from the PEM encoded files in the directory.
327 sslcredentials filename
329 Set the SSL credentials file location (see the -c com‐
330 mand-line flag).
331 sslenabled yes|true|on|no|false|off
333 Set whether or not encryption is attempted when talking
334 to servers (see the -E command-line flag).
335 sslrequired yes|true|on|no|false|off
337 Set whether or not encryption is required when talking to
338 servers (see the -U command-line flag).
339 striphigh yes|true|on|no|false|off
341 Set whether or not to strip the high bit off all data re‐
342 ceived (see the -7 command-line flag).
343 username user
345 Set the username passed to the server to user (see the -l
346 command-line flag).
347 terminal type
349 Define a configuration block when using a terminal of type type.
350 If the value of ``*'' is used, the configuration block will be
351 applied to all terminal types.
352 attach string|""
354 Set a string to print when successfully attached to a
355 console. Character substitions will be performed based
356 on the attachsubst value and occur before interpretation
357 of the special characters below. If the null string
358 (``""'') is used, no string will be printed. string is a
359 simple character string with the exception of `\' and
360 `^':
361 \a alert
363 \b backspace
364 \f form-feed
365 \n newline
366 \r carriage-return
367 \t tab
368 \v vertical-tab
369 \\ backslash
370 \^ circumflex
371 \ooo octal representation of a character (where
372 ooo is one to three octal digits)
373 \c character c
374 ^? delete
375 ^c control character (c is ``and''ed with 0x1f)
376 An interesting use of attach and attachsubst would be:
378 terminal xterm {
380 attach "^[]0;conserver: U@C^G";
381 attachsubst U=us,C=cs;
382 }
383 attachsubst c=t[n]f[,...]|""
385 Perform character substitutions on the attach value. A
386 series of replacements can be defined by specifying a
387 comma-separated list of c=t[n]f sequences where c is any
388 printable character, t specifies the replacement value, n
389 is a field length (optional), and f is the format string.
390 t can be one of the characters below, catagorized as a
391 string replacement or a numeric replacement, which dic‐
392 tates the use of the n and f fields.
393 String Replacement
395 u username
396 c console name
397 Numeric Replacement
399 none available (yet)
400 For string replacements, if the replacement isn't at
402 least n characters, it will be padded with space charac‐
403 ters on the left. f must be `s'. For numeric replace‐
404 ments, the value will be formatted to at least n charac‐
405 ters, padded with 0s if n begins with a 0, and space
406 characters otherwise. f must be either `d', `x' or `X',
407 specifying a decimal, lower-case hexadecimal, or an up‐
408 percase hexadecimal conversion. If the null string
409 (``""'') is used, no replacements will be done.
410 detach string|""
412 Set a string to print once detached from a console.
413 Character substitions will be performed based on the de‐
414 tachsubst value. See the attach option for an explana‐
415 tion of string. If the null string (``""'') is used, no
416 string will be printed.
417 detachsubst c=t[n]f[,...]|""
419 Perform character substitutions on the detach value. See
420 the attachsubst option for an explanation of the format
421 string.
422 A simple configuration to set a new default escape sequence and over‐
424 ride the master location would be:
425 # override options for all hosts
427 config * {
428 master localhost;
429 escape ^Ee;
430 }
431 # set things more specific to host1
432 # note: if the entries were reversed, host1
433 # would also use localhost.
434 config host1 {
435 master console1;
436 }
437
439 The connection can be controlled by a two-character escape sequence,
440 followed by a command. The default escape sequence is ``control-E c''
441 (octal 005 143). (The escape sequences are actually processed by the
442 server; see the conserver(8) man page for more information.) Commands
443 are:
444 . disconnect
446 ; move to another console
447 a attach read-write if nobody already is
448 b send broadcast message to all users on this console
449 c toggle flow control (don't do this)
450 d down the current console
451 ecc change the escape sequence to the next two characters
452 f forcibly attach read-write
453 g group info
454 i information dump
455 L toggle logging on/off
456 l? list the break sequences available
457 l0 send the break sequence associated with this console
458 l1-9a-z send the specific break sequence
459 m display the "message of the day"
460 o close (if open) and reopen the line (to clear errors (silo
461 overflows)) and the log file
462 p playback the last 60 lines of output
463 P set number of playback lines
464 r replay the last 20 lines of output
465 R set number of replay lines
466 s switch to spy mode (read only)
467 u show status of hosts/users in this group
468 v show the version of the group server
469 w who is using this console
470 x examine this group's devices and modes
471 z suspend this connection
472 ! invoke task
473 | attach a local command to the console
474 ? display list of commands
475 ^M (return) continue, ignore the escape sequence
476 ^R (ctrl-R) replay the last line only
477 \ooo send character having octal code ooo (must specify three
478 octal digits)
479 If any other character is hit after the escape sequence, all three
481 characters will be discarded. Note that a line break or a down command
482 can only be sent from a read-write connection. To send the escape se‐
483 quence through the connection one must redefine the outer escape se‐
484 quence, or use ^Ec\ooo to send the first escape character before typing
485 the second character directly.
486 In the -u output, the login ``<none>'' indicates no one is viewing that
488 console, and the login ``<spies>'' indicates that no one has a read-
489 write connection (only read-only).
490 When running a local command via ``^Ec|'', you can type `^C' to send
492 the command a SIGHUP, `^\' to send the command a SIGKILL, and `o' to
493 toggle the display of the console data.
494
496 console -u Outputs something like:
497 dumb up <none>
499 expert up ksb@mentor
500 tyro up <spies>
501 mentor up <none>
502 sage up fine@cis
503 The <none> indicates no one is viewing dumb or mentor,
505 the <spies> indicates only read-only connections exist
506 for tyro, and other login@host entries indicate users
507 attached read-write to sage and expert.
508 console -w Outputs something like:
510 ksb@extra attach 2days expert
512 file@cis attach 21:46 sage
513 dmr@alice spy 0:04 tyro
514 The third column is the idle time of the user. Either
516 hours:minutes or number of days is displayed.
517 console -e "^[1" lv426
519 Requests a connection to the host ``lv426'' with the es‐
520 cape characters set to ``escape one''.
521
523 The following default file locations may be overridden at compile time
524 or by the command-line options described above. Run console -V to see
525 the defaults set at compile time.
526 /etc/console.cf system-wide configuration file
528 $HOME/.consolerc per-user configuration file
529
531 It is possible to create a loop of console connections, with ugly re‐
532 sults. Never run console from within a console connection (unless you
533 set each escape sequence differently).
534 The -i output can produce more than the stated number of fields of in‐
536 formation if the user-provided information has embedded colons.
537 I'm sure there are more, I just don't know where they are. Please let
539 me know if you find any.
540
542 Thomas A. Fine, Ohio State Computer Science
543 Kevin Braunsdorf, Purdue University Computing Center
544 Bryan Stansell, conserver.com
545
547 conserver.cf(5), conserver.passwd(5), conserver(8)
548conserver-8.2.6 2020/10/19 CONSOLE(1)