Provided by: conserver-client_8.2.1-1_amd64 bug

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.

              sslcacertificatefile filename
                     Load the valid CA certificates for the SSL connection from the  PEM  encoded
                     file.

              sslcacertificatepath directory
                     Load  the  valid CA certificates for the SSL connection from the PEM encoded
                     files in the directory.

              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-9a-z      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
       !            invoke task
       |            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)