Provided by: conserver-client_8.1.18-1_i386 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.

              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)