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: [-7DEnUv] [-c cred] [-C config] [-M master] [-p port] [-l
15 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
31 below), 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
34 required (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
74 option 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 -luser Set the login name used for authentication to user. By
94 default, console uses $USER if its uid matches the user's
95 real uid, or $LOGNAME if its uid matches the user's real
96 uid, or else the name associated with the user's real uid.
97 -Mmaster The console client program polls master as the primary
99 server, rather than the default set at compile time (typi‐
100 cally ``console''). The default master may be changed at
101 compile time using the --with-master option. If --with-uds
102 is used to enable Unix domain sockets, however, this option
103 points console to the directory which holds those sockets.
104 The default master directory (``/tmp/conserver'') may be
105 changed at compile time using the --with-uds option.
106 -n Do not read the system-wide configuration file.
108 -pport Set the port to connect to. This may be either a port num‐
110 ber or a service name. The default port may be changed at
111 compile time using the --with-port option. If the --with-
112 uds option was used, this option is ignored.
113 -P Display the pid of the master daemon process on each server.
115 -q The console client connects to each server to request that
117 the server daemon quit (shut down). The root password of
118 the host(s) running conserver is required unless the local
119 host is listed as ``trusted'' in the conserver.cf file; in
120 that case, just press <return>.
121 -Q Same as -q but just acts on the primary server.
123 -r Display daemon versions. The console client connects to
125 each server to request its version information.
126 -R Same as -r but just acts on the primary server.
128 -s Request a read-only (spy mode) connection. In this mode all
130 the escape sequences (below) work, or report errors, but all
131 other keyboard input is discarded.
132 -t Send a text message to user@console. You may specify the
134 target as user (send to user, regardless of what console
135 they are attached to), @console (send to all users attached
136 to console), or user@console (send to user attached to con‐
137 sole).
138 -u Show a list of all consoles with status (`up', `down', or
140 `init') and attached users (user@host if attached read-
141 write, `<spies>' if only users in spy mode, or `<none>').
142 -U If encryption has been built into the code (--with-openssl),
144 encrypted client connections are, by default, a requirement.
145 This option allows the client to attempt an encrypted con‐
146 nection but fall back to a non-encrypted connection if the
147 server doesn't support encryption. If the encryption hand‐
148 shake is failing, disabling encryption on the client with
149 the -E option is probably what you want.
150 -v Be more verbose when building the connection(s). Use this
152 option in combination with any of `show' options (below) for
153 added benefit.
154 -V Output the version and settings of the console client pro‐
156 gram and then exit.
157 -w Show a list of all who are currently connected to consoles,
159 including the hostnames where the console connections origi‐
160 nate and the idle times. This is useful to see if anybody
161 is actively using the console system if it becomes necessary
162 to shut down conserver.
163 -W Same as -w but just acts on the primary server.
165 -x Show a list of consoles and devices.
167 -zcmd Sends a command (cmd) to each server and displays the
169 result. The valid commands are:
170 bringup Try to connect all consoles marked as down (this
172 is equivalent to sending the server a SIGUSR1)
173 SIGUSR1 Same as bringup
174 help Displays the help message
175 pid Returns the pid of the server (this is equiva‐
176 lent to -P)
177 quit Instructs the server to shut down (this is
178 equivalent to -q or sending the server a
179 SIGTERM)
180 SIGTERM Same as quit
181 reconfig Instructs the server to reload the configuration
182 file, then perform the actions of reopen (this
183 is equivalent to sending the server a SIGHUP)
184 SIGHUP Same as reconfig
185 reopen Instructs the server to reopen all logfiles,
186 then perform the actions of bringup (this is
187 equivalent to sending the server a SIGUSR2)
188 SIGUSR2 Same as reopen
189 version Returns the version of the server (this is
190 equivalent to -V)
191 -Zcmd Same as -z but just sends cmd to the primary server.
193 The -A, -F, or -S options have the same effect as their lower-case
195 variants. In addition, they each request the last 20 lines of the con‐
196 sole output after making the connection (as if ``^Ecr'' were typed).
197 The -i, -u, -w, and -x options can be given a console name, which will
199 limit their output to that console.
200 The -i option outputs status information regarding each console in 15
202 colon-separated fields.
203 name The name of the console.
205 hostname,pid,socket
207 The hostname, pid, and socket number of the child process manag‐
208 ing the console.
209 type The type of console. Values will be a `/' for a local device,
211 `|' for a command, `!' for a remote port, `%' for a Unix domain
212 socket, and `#' for a noop console.
213 console-details
215 The details regarding the console. The values here (all comma-
216 separated) depend on the type of the console. Local devices
217 will have values of the device file, baud rate/parity, and file
218 descriptor for the device. Commands will have values of the
219 command, the command's pid, the pseudo-tty, and file descriptor
220 for the pseudo-tty. Remote ports will have values of the remote
221 hostname, remote port number, ``raw'' or ``telnet'' protocol,
222 and file descriptor for the socket connection. Unix domain
223 sockets will have the path to the socket and the file descriptor
224 for the socket connection. Noop consoles will have nothing.
225 users-list
227 The details of each user connected to the console. The details
228 for each user are an `@' separated list of `w', `r', or `s' (for
229 read-write, read-only, or suspended), username, hostname the
230 user is on, the user's idle time, and (for `r' and `s' users
231 only) ``rw'' or ``ro'' (if the user wants read-write mode or
232 not). Each user bundle is separated by commas.
233 state The state of the console. Values with either be ``up'',
235 ``down'', or ``init''.
236 perm This value will either be ``rw'' or ``ro''. It will only be
238 ``ro'' if the console is a local device (`/' type) and the per‐
239 missions are such that the server can open the file for read,
240 but not write.
241 logfile-details
243 The details regarding the logging for the console. The comma-
244 separated values will be the logfile, ``log'' or ``nolog'' (if
245 logging is on or not - toggled via ``^EcL''), ``act'' or
246 ``noact'' (if activity logging is enabled or not - the `a' time‐
247 stamp option), the timestamp interval, and the file descriptor
248 of the logfile.
249 break The default break sequence used for the console.
251 reup If the console is currently down and the automatic reconnection
253 code is at work, it will have the value of ``autoup'', otherwise
254 it will be ``noautoup''.
255 aliases
257 The console aliases are presented in a comma-separated list.
258 options
260 The active options for the console are presented in a comma-sep‐
261 arated list.
262 initcmd
264 The initcmd configuration option for the console.
265 idletimeout
267 The idletimeout configuration option for the console.
268 idlestring
270 The idlestring configuration option for the console.
271
273 Console reads configuration information from the system-wide configura‐
274 tion file (console.cf), then the per-user configuration file (.consol‐
275 erc), and then applies command-line arguments. Each configuration
276 location can override the previous. The same happens when parsing an
277 individual file - the later entries always override the earlier
278 entries. Because of that, you should put ``global'' defaults first and
279 more specific defaults second.
280 The configuration file is read using the same parser as con‐
282 server.cf(5), and you should check that manpage for parser details.
283 Console recognizes the following configuration blocks.
284 config hostname|ipaddr
286 Define a configuration block for the client host named hostname
287 or using the address ipaddr. If the value of ``*'' is used, the
288 configuration block will be applied to all client hosts.
289 escape esc
291 Set the escape sequence (see the -e command-line flag).
292 master master
294 Set the default master to master (see the -M command-line
295 flag).
296 playback num|""
298 Override the playback length for the p escape command to
299 num lines (if the server supports it). Using the special
300 value of ``0'' will cause the client to use the number of
301 lines of the current terminal (if that can be deter‐
302 mined). If the null string (``""'') is used, the play‐
303 back length will not be overridden.
304 port port
306 Set the default port to port (see the -p command-line
307 flag).
308 replay num|""
310 Override the replay length for the r escape command to
311 num lines (if the server supports it). Using the special
312 value of ``0'' will cause the client to use the number of
313 lines of the current terminal (if that can be deter‐
314 mined). If the null string (``""'') is used, the replay
315 length will not be overridden.
316 sslcacertificatefile filename
318 Load the valid CA certificates for the SSL connection
319 from the PEM encoded file.
320 sslcacertificatepath directory
322 Load the valid CA certificates for the SSL connection
323 from the PEM encoded files in the directory.
324 sslcredentials filename
326 Set the SSL credentials file location (see the -c com‐
327 mand-line flag).
328 sslenabled yes|true|on|no|false|off
330 Set whether or not encryption is attempted when talking
331 to servers (see the -E command-line flag).
332 sslrequired yes|true|on|no|false|off
334 Set whether or not encryption is required when talking to
335 servers (see the -U command-line flag).
336 striphigh yes|true|on|no|false|off
338 Set whether or not to strip the high bit off all data
339 received (see the -7 command-line flag).
340 username user
342 Set the username passed to the server to user (see the -l
343 command-line flag).
344 terminal type
346 Define a configuration block when using a terminal of type type.
347 If the value of ``*'' is used, the configuration block will be
348 applied to all terminal types.
349 attach string|""
351 Set a string to print when successfully attached to a
352 console. Character substitions will be performed based
353 on the attachsubst value and occur before interpretation
354 of the special characters below. If the null string
355 (``""'') is used, no string will be printed. string is a
356 simple character string with the exception of `\' and
357 `^':
358 \a alert
360 \b backspace
361 \f form-feed
362 \n newline
363 \r carriage-return
364 \t tab
365 \v vertical-tab
366 \\ backslash
367 \^ circumflex
368 \ooo octal representation of a character (where
369 ooo is one to three octal digits)
370 \c character c
371 ^? delete
372 ^c control character (c is ``and''ed with 0x1f)
373 An interesting use of attach and attachsubst would be:
375 terminal xterm {
377 attach "^[]0;conserver: U@C^G";
378 attachsubst U=us,C=cs;
379 }
380 attachsubst c=t[n]f[,...]|""
382 Perform character substitutions on the attach value. A
383 series of replacements can be defined by specifying a
384 comma-separated list of c=t[n]f sequences where c is any
385 printable character, t specifies the replacement value, n
386 is a field length (optional), and f is the format string.
387 t can be one of the characters below, catagorized as a
388 string replacement or a numeric replacement, which dic‐
389 tates the use of the n and f fields.
390 String Replacement
392 u username
393 c console name
394 Numeric Replacement
396 none available (yet)
397 For string replacements, if the replacement isn't at
399 least n characters, it will be padded with space charac‐
400 ters on the left. f must be `s'. For numeric replace‐
401 ments, the value will be formatted to at least n charac‐
402 ters, padded with 0s if n begins with a 0, and space
403 characters otherwise. f must be either `d', `x' or `X',
404 specifying a decimal, lower-case hexadecimal, or an
405 uppercase hexadecimal conversion. If the null string
406 (``""'') is used, no replacements will be done.
407 detach string|""
409 Set a string to print once detached from a console.
410 Character substitions will be performed based on the
411 detachsubst value. See the attach option for an explana‐
412 tion of string. If the null string (``""'') is used, no
413 string will be printed.
414 detachsubst c=t[n]f[,...]|""
416 Perform character substitutions on the detach value. See
417 the attachsubst option for an explanation of the format
418 string.
419 A simple configuration to set a new default escape sequence and over‐
421 ride the master location would be:
422 # override options for all hosts
424 config * {
425 master localhost;
426 escape ^Ee;
427 }
428 # set things more specific to host1
429 # note: if the entries were reversed, host1
430 # would also use localhost.
431 config host1 {
432 master console1;
433 }
434
436 The connection can be controlled by a two-character escape sequence,
437 followed by a command. The default escape sequence is ``control-E c''
438 (octal 005 143). (The escape sequences are actually processed by the
439 server; see the conserver(8) man page for more information.) Commands
440 are:
441 . disconnect
443 ; move to another console
444 a attach read-write if nobody already is
445 b send broadcast message to all users on this console
446 c toggle flow control (don't do this)
447 d down the current console
448 ecc change the escape sequence to the next two characters
449 f forcibly attach read-write
450 g group info
451 i information dump
452 L toggle logging on/off
453 l? list the break sequences available
454 l0 send the break sequence associated with this console
455 l1-9a-z send the specific break sequence
456 m display the "message of the day"
457 o close (if open) and reopen the line (to clear errors (silo
458 overflows)) and the log file
459 p playback the last 60 lines of output
460 P set number of playback lines
461 r replay the last 20 lines of output
462 R set number of replay lines
463 s switch to spy mode (read only)
464 u show status of hosts/users in this group
465 v show the version of the group server
466 w who is using this console
467 x examine this group's devices and modes
468 z suspend this connection
469 ! invoke task
470 | attach a local command to the console
471 ? display list of commands
472 ^M (return) continue, ignore the escape sequence
473 ^R (ctrl-R) replay the last line only
474 \ooo send character having octal code ooo (must specify three
475 octal digits)
476 If any other character is hit after the escape sequence, all three
478 characters will be discarded. Note that a line break or a down command
479 can only be sent from a read-write connection. To send the escape
480 sequence through the connection one must redefine the outer escape
481 sequence, or use ^Ec\ooo to send the first escape character before typ‐
482 ing the second character directly.
483 In the -u output, the login ``<none>'' indicates no one is viewing that
485 console, and the login ``<spies>'' indicates that no one has a read-
486 write connection (only read-only).
487 When running a local command via ``^Ec|'', you can type `^C' to send
489 the command a SIGHUP, `^\' to send the command a SIGKILL, and `o' to
490 toggle the display of the console data.
491
493 console -u Outputs something like:
494 dumb up <none>
496 expert up ksb@mentor
497 tyro up <spies>
498 mentor up <none>
499 sage up fine@cis
500 The <none> indicates no one is viewing dumb or mentor,
502 the <spies> indicates only read-only connections exist
503 for tyro, and other login@host entries indicate users
504 attached read-write to sage and expert.
505 console -w Outputs something like:
507 ksb@extra attach 2days expert
509 file@cis attach 21:46 sage
510 dmr@alice spy 0:04 tyro
511 The third column is the idle time of the user. Either
513 hours:minutes or number of days is displayed.
514 console -e "^[1" lv426
516 Requests a connection to the host ``lv426'' with the
517 escape characters set to ``escape one''.
518
520 The following default file locations may be overridden at compile time
521 or by the command-line options described above. Run console -V to see
522 the defaults set at compile time.
523 /etc/console.cf system-wide configuration file
525 $HOME/.consolerc per-user configuration file
526
528 It is possible to create a loop of console connections, with ugly
529 results. Never run console from within a console connection (unless
530 you set each escape sequence differently).
531 The -i output can produce more than the stated number of fields of
533 information if the user-provided information has embedded colons.
534 I'm sure there are more, I just don't know where they are. Please let
536 me know if you find any.
537
539 Thomas A. Fine, Ohio State Computer Science
540 Kevin Braunsdorf, Purdue University Computing Center
541 Bryan Stansell, conserver.com
542
544 conserver.cf(5), conserver.passwd(5), conserver(8)
545conserver-8.2.1 2015/06/02 CONSOLE(1)