NAME
console - console server client program
SYNOPSIS
console [generic-args] [-aAfFsS] [-e esc] console
console [generic-args] [-iIuwWx] [console]
console [generic-args] [-hPqQrRV] [-[bB] message] [-d [user][@console]]
[-t [user][@console] message] [-[zZ] cmd]
generic-args: [-7DEnUv] [-c cred] [-C config] [-M master] [-p port] [-l
user]
DESCRIPTION
Console is used to manipulate console terminals remotely or to poll
running conserver(8) daemons for status information.
In the first form above, console asks the user’s password before
granting interactive access to a console (on a non-trusted system),
since such a session may provide single-user access. If the server’s
autocompletion feature is enabled, only as much of the console name as
is required to identify it uniquely to the server is required.
For non-interactive options, console outputs only the requested
information and exits.
Console knows only of a primary conserver host (see the -M option
below), to which it initially connects. In a multi-server environment,
the primary server may refer the client to a different server handling
the requested console, or it will provide a list of all servers if
required (as when console is invoked with the -r option). Console then
opens connections to the appropriate server(s). It is not necessary
for the user of console to know which server manages which consoles, as
long as console knows a valid primary server and all available consoles
are listed in the primary server’s configuration file.
OPTIONS
Options may be given as separate arguments (e.g., -v -w) or clustered
(e.g., -vw). Options and their arguments may be separated by optional
white space. Option arguments containing spaces or other characters
special to the shell must be quoted.
-7 Strip the high bit off of all data received, whether from
user input or from the server, before any processing occurs.
Disallows escape sequence characters with the high bit set.
-a Access a console with a two-way (read-write) connection
(this is the default). The connection is dropped to spy
mode if someone else is attached read-write.
-bmessage Broadcast a message to all users connected to each server.
-Bmessage Same as -b but just send a message to users on the primary
server.
-ccred Load an SSL certificate and key from the PEM encoded file
cred.
-Cconfig Use the per-user configuration file config.
-d Disconnect the users specified by user@console. You may
specify the target as user (disconnect the user, regardless
of what console they are attached to), @console (disconnect
all users attached to console), or user@console (disconnect
the user attached to console).
-D Enable debugging output.
-eesc Set the initial two-character escape sequence to those
represented by esc. Any of the forms output by cat(1)’s -v
option are accepted. The default value is ‘‘^Ec’’.
-E If encryption has been built into the code (--with-openssl),
encrypted client connections are, by default, a requirement.
This option disables any attempt at creating an encrypted
connection. If you’d like to use encrypted connections when
your server supports it, but fallback to non-encrypted
otherwise, the -U option is what you want.
-f Same as -a except it will force any existing connection into
spy mode.
-h Display a brief help message.
-i Display status information in a machine-parseable format
(see below for the details).
-I Same as -i but just acts on the primary server.
-luser Set the login name used for authentication to user. By
default, console uses $USER if its uid matches the user’s
real uid, or $LOGNAME if its uid matches the user’s real
uid, or else the name associated with the user’s real uid.
-Mmaster The console client program polls master as the primary
server, rather than the default set at compile time
(typically ‘‘console’’). The default master may be changed
at compile time using the --with-master option. If --with-
uds is used to enable Unix domain sockets, however, this
option points console to the directory which holds those
sockets. The default master directory (‘‘/tmp/conserver’’)
may be changed at compile time using the --with-uds option.
-n Do not read the system-wide configuration file.
-pport Set the port to connect to. This may be either a port
number or a service name. The default port may be changed
at compile time using the --with-port option. If the
--with-uds option was used, this option is ignored.
-P Display the pid of the master daemon process on each server.
-q The console client connects to each server to request that
the server daemon quit (shut down). The root password of
the host(s) running conserver is required unless the local
host is listed as ‘‘trusted’’ in the conserver.cf file; in
that case, just press <return>.
-Q Same as -q but just acts on the primary server.
-r Display daemon versions. The console client connects to
each server to request its version information.
-R Same as -r but just acts on the primary server.
-s Request a read-only (spy mode) connection. In this mode all
the escape sequences (below) work, or report errors, but all
other keyboard input is discarded.
-t Send a text message to user@console. You may specify the
target as user (send to user, regardless of what console
they are attached to), @console (send to all users attached
to console), or user@console (send to user attached to
console).
-u Show a list of all consoles with status (‘up’, ‘down’, or
‘init’) and attached users (user@host if attached read-
write, ‘<spies>’ if only users in spy mode, or ‘<none>’).
-U If encryption has been built into the code (--with-openssl),
encrypted client connections are, by default, a requirement.
This option allows the client to attempt an encrypted
connection but fall back to a non-encrypted connection if
the server doesn’t support encryption. If the encryption
handshake is failing, disabling encryption on the client
with the -E option is probably what you want.
-v Be more verbose when building the connection(s). Use this
option in combination with any of ‘show’ options (below) for
added benefit.
-V Output the version and settings of the console client
program and then exit.
-w Show a list of all who are currently connected to consoles,
including the hostnames where the console connections
originate and the idle times. This is useful to see if
anybody is actively using the console system if it becomes
necessary to shut down conserver.
-W Same as -w but just acts on the primary server.
-x Show a list of consoles and devices.
-zcmd Sends a command (cmd) to each server and displays the
result. The valid commands are:
bringup Try to connect all consoles marked as down (this
is equivalent to sending the server a SIGUSR1)
SIGUSR1 Same as bringup
help Displays the help message
pid Returns the pid of the server (this is
equivalent to -P)
quit Instructs the server to shut down (this is
equivalent to -q or sending the server a
SIGTERM)
SIGTERM Same as quit
reconfig Instructs the server to reload the configuration
file, then perform the actions of reopen (this
is equivalent to sending the server a SIGHUP)
SIGHUP Same as reconfig
reopen Instructs the server to reopen all logfiles,
then perform the actions of bringup (this is
equivalent to sending the server a SIGUSR2)
SIGUSR2 Same as reopen
version Returns the version of the server (this is
equivalent to -V)
-Zcmd Same as -z but just sends cmd to the primary server.
The -A, -F, or -S options have the same effect as their lower-case
variants. In addition, they each request the last 20 lines of the
console output after making the connection (as if ‘‘^Ecr’’ were typed).
The -i, -u, -w, and -x options can be given a console name, which will
limit their output to that console.
The -i option outputs status information regarding each console in 15
colon-separated fields.
name The name of the console.
hostname,pid,socket
The hostname, pid, and socket number of the child process
managing the console.
type The type of console. Values will be a ‘/’ for a local device,
‘|’ for a command, ‘!’ for a remote port, ‘%’ for a Unix domain
socket, and ‘#’ for a noop console.
console-details
The details regarding the console. The values here (all comma-
separated) depend on the type of the console. Local devices
will have values of the device file, baud rate/parity, and file
descriptor for the device. Commands will have values of the
command, the command’s pid, the pseudo-tty, and file descriptor
for the pseudo-tty. Remote ports will have values of the remote
hostname, remote port number, ‘‘raw’’ or ‘‘telnet’’ protocol,
and file descriptor for the socket connection. Unix domain
sockets will have the path to the socket and the file descriptor
for the socket connection. Noop consoles will have nothing.
users-list
The details of each user connected to the console. The details
for each user are an ‘@’ separated list of ‘w’, ‘r’, or ‘s’ (for
read-write, read-only, or suspended), username, hostname the
user is on, the user’s idle time, and (for ‘r’ and ‘s’ users
only) ‘‘rw’’ or ‘‘ro’’ (if the user wants read-write mode or
not). Each user bundle is separated by commas.
state The state of the console. Values with either be ‘‘up’’,
‘‘down’’, or ‘‘init’’.
perm This value will either be ‘‘rw’’ or ‘‘ro’’. It will only be
‘‘ro’’ if the console is a local device (‘/’ type) and the
permissions are such that the server can open the file for read,
but not write.
logfile-details
The details regarding the logging for the console. The comma-
separated values will be the logfile, ‘‘log’’ or ‘‘nolog’’ (if
logging is on or not - toggled via ‘‘^EcL’’), ‘‘act’’ or
‘‘noact’’ (if activity logging is enabled or not - the ‘a’
timestamp option), the timestamp interval, and the file
descriptor of the logfile.
break The default break sequence used for the console.
reup If the console is currently down and the automatic reconnection
code is at work, it will have the value of ‘‘autoup’’, otherwise
it will be ‘‘noautoup’’.
aliases
The console aliases are presented in a comma-separated list.
options
The active options for the console are presented in a comma-
separated list.
initcmd
The initcmd configuration option for the console.
idletimeout
The idletimeout configuration option for the console.
idlestring
The idlestring configuration option for the console.
CONFIGURATION
Console reads configuration information from the system-wide
configuration file (console.cf), then the per-user configuration file
(.consolerc), and then applies command-line arguments. Each
configuration location can override the previous. The same happens
when parsing an individual file - the later entries always override the
earlier entries. Because of that, you should put ‘‘global’’ defaults
first and more specific defaults second.
The configuration file is read using the same parser as
conserver.cf(5), and you should check that manpage for parser details.
Console recognizes the following configuration blocks.
config hostname|ipaddr
Define a configuration block for the client host named hostname
or using the address ipaddr. If the value of ‘‘*’’ is used, the
configuration block will be applied to all client hosts.
escape esc
Set the escape sequence (see the -e command-line flag).
master master
Set the default master to master (see the -M command-line
flag).
playback num|""
Override the playback length for the p escape command to
num lines (if the server supports it). Using the special
value of ‘‘0’’ will cause the client to use the number of
lines of the current terminal (if that can be
determined). If the null string (‘‘""’’) is used, the
playback length will not be overridden.
port port
Set the default port to port (see the -p command-line
flag).
replay num|""
Override the replay length for the r escape command to
num lines (if the server supports it). Using the special
value of ‘‘0’’ will cause the client to use the number of
lines of the current terminal (if that can be
determined). If the null string (‘‘""’’) is used, the
replay length will not be overridden.
sslcredentials filename
Set the SSL credentials file location (see the -c
command-line flag).
sslenabled yes|true|on|no|false|off
Set whether or not encryption is attempted when talking
to servers (see the -E command-line flag).
sslrequired yes|true|on|no|false|off
Set whether or not encryption is required when talking to
servers (see the -U command-line flag).
striphigh yes|true|on|no|false|off
Set whether or not to strip the high bit off all data
received (see the -7 command-line flag).
username user
Set the username passed to the server to user (see the -l
command-line flag).
terminal type
Define a configuration block when using a terminal of type type.
If the value of ‘‘*’’ is used, the configuration block will be
applied to all terminal types.
attach string|""
Set a string to print when successfully attached to a
console. Character substitions will be performed based
on the attachsubst value and occur before interpretation
of the special characters below. If the null string
(‘‘""’’) is used, no string will be printed. string is a
simple character string with the exception of ‘\’ and
‘^’:
\a alert
\b backspace
\f form-feed
\n newline
\r carriage-return
\t tab
\v vertical-tab
\\ backslash
\^ circumflex
\ooo octal representation of a character (where
ooo is one to three octal digits)
\c character c
^? delete
^c control character (c is ‘‘and’’ed with
0x1f)
An interesting use of attach and attachsubst would be:
terminal xterm {
attach "^[]0;conserver: U@C^G";
attachsubst U=us,C=cs;
}
attachsubst c=t[n]f[,...]|""
Perform character substitutions on the attach value. A
series of replacements can be defined by specifying a
comma-separated list of c=t[n]f sequences where c is any
printable character, t specifies the replacement value, n
is a field length (optional), and f is the format string.
t can be one of the characters below, catagorized as a
string replacement or a numeric replacement, which
dictates the use of the n and f fields.
String Replacement
u username
c console name
Numeric Replacement
none available (yet)
For string replacements, if the replacement isn’t at
least n characters, it will be padded with space
characters on the left. f must be ‘s’. For numeric
replacements, the value will be formatted to at least n
characters, padded with 0s if n begins with a 0, and
space characters otherwise. f must be either ‘d’, ‘x’ or
‘X’, specifying a decimal, lower-case hexadecimal, or an
uppercase hexadecimal conversion. If the null string
(‘‘""’’) is used, no replacements will be done.
detach string|""
Set a string to print once detached from a console.
Character substitions will be performed based on the
detachsubst value. See the attach option for an
explanation of string. If the null string (‘‘""’’) is
used, no string will be printed.
detachsubst c=t[n]f[,...]|""
Perform character substitutions on the detach value. See
the attachsubst option for an explanation of the format
string.
A simple configuration to set a new default escape sequence and
override the master location would be:
# override options for all hosts
config * {
master localhost;
escape ^Ee;
}
# set things more specific to host1
# note: if the entries were reversed, host1
# would also use localhost.
config host1 {
master console1;
}
ESCAPE SEQUENCES
The connection can be controlled by a two-character escape sequence,
followed by a command. The default escape sequence is ‘‘control-E c’’
(octal 005 143). (The escape sequences are actually processed by the
server; see the conserver(8) man page for more information.) Commands
are:
. disconnect
; move to another console
a attach read-write if nobody already is
b send broadcast message to all users on this console
c toggle flow control (don’t do this)
d down the current console
ecc change the escape sequence to the next two characters
f forcibly attach read-write
g group info
i information dump
L toggle logging on/off
l? list the break sequences available
l0 send the break sequence associated with this console
l1-9 send the specific break sequence
m display the "message of the day"
o close (if open) and reopen the line (to clear errors (silo
overflows)) and the log file
p playback the last 60 lines of output
P set number of playback lines
r replay the last 20 lines of output
R set number of replay lines
s switch to spy mode (read-only)
u show status of hosts/users in this group
v show the version of the group server
w who is using this console
x examine this group’s devices and modes
z suspend this connection
| attach a local command to the console
? display list of commands
^M (return) continue, ignore the escape sequence
^R (ctrl-R) replay the last line only
\ooo send character having octal code ooo (must specify three
octal digits)
If any other character is hit after the escape sequence, all three
characters will be discarded. Note that a line break or a down command
can only be sent from a read-write connection. To send the escape
sequence through the connection one must redefine the outer escape
sequence, or use ^Ec\ooo to send the first escape character before
typing the second character directly.
In the -u output, the login ‘‘<none>’’ indicates no one is viewing that
console, and the login ‘‘<spies>’’ indicates that no one has a read-
write connection (only read-only).
When running a local command via ‘‘^Ec|’’, you can type ‘^C’ to send
the command a SIGHUP, ‘^\’ to send the command a SIGKILL, and ‘o’ to
toggle the display of the console data.
EXAMPLES
console -u Outputs something like:
dumb up <none>
expert up ksb@mentor
tyro up <spies>
mentor up <none>
sage up fine@cis
The <none> indicates no one is viewing dumb or mentor,
the <spies> indicates only read-only connections exist
for tyro, and other login@host entries indicate users
attached read-write to sage and expert.
console -w Outputs something like:
ksb@extra attach 2days expert
file@cis attach 21:46 sage
dmr@alice spy 0:04 tyro
The third column is the idle time of the user. Either
hours:minutes or number of days is displayed.
console -e "^[1" lv426
Requests a connection to the host ‘‘lv426’’ with the
escape characters set to ‘‘escape one’’.
FILES
The following default file locations may be overridden at compile time
or by the command-line options described above. Run console -V to see
the defaults set at compile time.
/etc/console.cf system-wide configuration file
$HOME/.consolerc per-user configuration file
BUGS
It is possible to create a loop of console connections, with ugly
results. Never run console from within a console connection (unless
you set each escape sequence differently).
The -i output can produce more than the stated number of fields of
information if the user-provided information has embedded colons.
I’m sure there are more, I just don’t know where they are. Please let
me know if you find any.
AUTHORS
Thomas A. Fine, Ohio State Computer Science
Kevin Braunsdorf, Purdue University Computing Center
Bryan Stansell, conserver.com
SEE ALSO
conserver.cf(5), conserver.passwd(5), conserver(8)