1CONSERVER(8)                       conserver                      CONSERVER(8)
2
3
4

NAME

6       conserver - console server daemon
7

SYNOPSIS

9       conserver  [-7dDEFhinoRSuvV]  [-a  type] [-m max] [-M master] [-p port]
10       [-b port] [-c cred] [-C config] [-P passwd] [-L logfile] [-O  min]  [-U
11       logfile]
12

DESCRIPTION

14       Conserver  is  the daemon that manages remote access to system consoles
15       by multiple users via the console(1) client  program  and  (optionally)
16       log  the  console  output.  It can connect to consoles via local serial
17       ports, Unix domain sockets, TCP sockets (for terminal servers  and  the
18       like), or any external program.
19
20       When  started,  conserver reads the conserver.cf(5) file for details of
21       each console.  The console type, logging  options,  serial  or  network
22       parameters,  and  user  access levels are just a few of the things that
23       can be specified.  Command-line  options  are  then  applied,  possibly
24       overriding  conserver.cf(5)  settings.   Conserver categorizes consoles
25       into two types: those it should actively manage, and  those  it  should
26       just  know about, so it can refer clients to other conserver instances.
27       If the master value of a console matches the hostname or ip address  of
28       the  local machine, conserver will actively manage the console.  Other‐
29       wise, it's considered a ``remote'' console and managed by  a  different
30       server.   Conserver  forks  a  child for each group of consoles it must
31       manage and assigns each process a port number to listen on.  The  maxi‐
32       mum  number  of consoles managed by each child process is set using the
33       -m option.  The console(1) client program communicates with the  master
34       console  server  process  to find the port (and host, in a multi-server
35       configuration) on which the appropriate child is listening.   Conserver
36       restricts  connections from clients based on the host access section of
37       its conserver.cf(5) file, restricts users based on the  console  access
38       lists  of the conserver.cf(5) file, and authenticates users against its
39       conserver.passwd(5) file.  Conserver can also  restrict  clients  using
40       the  tcp-wrappers package (enabled using --with-libwrap).  This authen‐
41       tication is done before consulting the conserver.cf(5) access list.
42
43       When Unix domain  sockets  are  used  between  the  client  and  server
44       (enabled using --with-uds), authentication checks are done on the hard‐
45       coded address ``127.0.0.1''.  Automatic client redirection is also dis‐
46       abled  (as  if the -R option was used) since the client cannot communi‐
47       cate with remote servers.  The directory used to hold  the  sockets  is
48       checked  to  make  sure  it's empty when the server starts.  The server
49       will not remove any files in the directory itself,  just  in  case  the
50       directory  is accidentally specified as ``/etc'' or some other critical
51       location.  The server will do its best to remove all the  sockets  when
52       it shuts down, but it could stop ungracefully (crash, ``kill -9'', etc)
53       and leave files behind.  It would then be up to the admin  (or  a  cre‐
54       ative  startup script) to clean up the directory before the server will
55       start again.
56
57       Conserver completely controls any connection to a console.  All  escape
58       sequences given by the user to console are passed to the server without
59       interpretation.   The  server  recognizes  and  processes  all   escape
60       sequences.
61
62       The  conserver  parent  process  will  automatically  respawn any child
63       process that dies.  The following signals are propagated by the  parent
64       process to its children.
65
66       SIGTERM   Close all connections and exit.
67
68       SIGHUP    Reread  the  configuration file.  New consoles are managed by
69                 forking  off  new  children,  deleted  consoles  (and   their
70                 clients)  are  dropped,  and changes to consoles are done "in
71                 place", resetting the console port (bringing it down and  up)
72                 only  when  necessary.  The console name is used to determine
73                 when consoles have been added/removed/changed.   All  actions
74                 performed by SIGUSR2 are also performed.
75
76       SIGUSR1   Try to connect to any consoles marked as down.  This can come
77                 in handy if you had a terminal server (or more)  that  wasn't
78                 accepting  connections  at  startup and you want conserver to
79                 try to reconnect to all those downed ports.
80
81       SIGUSR2   Close and reopen all console logfiles and, if in daemon  mode
82                 (-d  option),  the  error  logfile  (see the -L option).  All
83                 actions performed by SIGUSR1 are also performed.
84
85       Consoles which have no current client connection might  produce  impor‐
86       tant  error messages.  With the -u option, these ``unloved'' errors are
87       labeled with a machine name and output on stdout (or, in  daemon  mode,
88       to the logfile).  This allows a live operator or an automated log scan‐
89       ner to find otherwise unseen errors by watching in a single location.
90
91       Conserver must be run as root if it is to bind to a port under 1024  or
92       if  it  must  read protected password files (like shadow passwords) for
93       authentication (see conserver.passwd(5)).  Otherwise, it may be run  by
94       any user, with -p used to specify a port above 1024.
95
96       If  encryption has been built into the code (--with-openssl), encrypted
97       client connections (without certificate exchanges) happen  by  default.
98       To  add  certificate  exchanges,  use the -c option with the client and
99       server.  For authentication of the certificates to  work,  the  signing
100       certificate  must  be  properly trusted, which usually means the public
101       portion is in OPENSSL_ROOT/ssl/certs (on both  the  client  and  server
102       sides).   See  the  sample  self-signing certificate making script con‐
103       trib/maketestcerts for further clues.  To  allow  non-encrypted  client
104       connections  (in  addition to encrypted client connections), use the -E
105       option.
106

OPTIONS

108       Options may be given as separate arguments (e.g., -n -d)  or  clustered
109       (e.g.,  -nd).  Options and their arguments may be separated by optional
110       white space.  Option arguments containing spaces  or  other  characters
111       special to the shell must be quoted.
112
113       -7          Strip  the  high bit off of all data received, whether from
114                   the console client or from the console device,  before  any
115                   processing occurs.
116
117       -atype      Set  the  default access type for incoming connections from
118                   console clients: `r' for refused  (the  default),  `a'  for
119                   allowed,  or  `t'  for  trusted.  This applies to hosts for
120                   which no matching entry is found in the access  section  of
121                   conserver.cf(5).
122
123       -bport      Set  the  base  port for children to listen on.  Each child
124                   starts looking for free ports at port and  working  upward,
125                   trying a maximum number of ports equal to twice the maximum
126                   number of groups.  If no free ports are available  in  that
127                   range,  conserver  exits.   By  default, conserver lets the
128                   operating system choose a free port.
129
130       -ccred      Load an SSL certificate and key from the PEM  encoded  file
131                   cred.
132
133       -Cconfig    Read  configuration  information from the file config.  The
134                   default config may be changed at  compile  time  using  the
135                   --with-cffile option.
136
137       -d          Become a daemon.  Disconnects from the controlling terminal
138                   and sends all output (including any debug  output)  to  the
139                   logfile (see -L).
140
141       -D          Enable  debugging  output,  sent  to  stderr.   Multiple -D
142                   options increases debug output.
143
144       -E          If  encryption  has  been  built  into  the  code  (--with-
145                   openssl),  encrypted  client connections are a requirement.
146                   This  option  allows  non-encrypted  clients  (as  well  as
147                   encrypted clients) to connect to consoles.
148
149       -F          Do  not  automatically  reinitialize  failed  (unexpectedly
150                   closed) consoles.  If the console is a program (`|' syntax)
151                   and  it  closes  with  a  zero  exit status, the console is
152                   reinitialized regardless  of  this  option.   Without  this
153                   option,  a  console  is  immediately  reopened, and if that
154                   fails, retried every minute until successful.  This  option
155                   has no effect on the -o and -O options.
156
157       -h          Output a brief help message.
158
159       -i          Initiate console connections on demand (and close them when
160                   not used).
161
162       -Llogfile   Log errors and  informational  messages  to  logfile  after
163                   startup  in  daemon  mode (-d).  This option does not apply
164                   when not running in daemon mode.  The default  logfile  may
165                   be changed at compile time using the --with-logfile option.
166
167       -mmax       Set  the maximum consoles managed per process.  The default
168                   max may be changed at compile time using the --with-maxmemb
169                   option.
170
171       -Mmaster    Normally,  this allows conserver to bind to a particular IP
172                   address (like `127.0.0.1') instead of all interfaces.   The
173                   default  is  to bind to all addresses.  However, if --with-
174                   uds  was  used  to   enable   Unix   domain   sockets   for
175                   client/server  communication,  this points conserver to the
176                   directory where it should store the sockets.   The  default
177                   master  directory  (``/tmp/conserver'')  may  be changed at
178                   compile time using the --with-uds option.
179
180       -n          Obsolete (now a no-op); see -u.
181
182       -o          Normally, a client connecting to a ``downed'' console  does
183                   just  that.   Using  this option, the server will automati‐
184                   cally attempt to open (``bring up'') the console  when  the
185                   client connects.
186
187       -Omin       Enable  periodic  attempts  (every  min  minutes)  to  open
188                   (``bring up'') all downed consoles (similar  to  sending  a
189                   SIGUSR1).  Without this option, or if min is zero, no peri‐
190                   odic attempts occur.
191
192       -pport      Set the TCP port for the master process to listen on.  This
193                   may be either a port number or a service name.  The default
194                   port, ``conserver'' (typically 782), may be changed at com‐
195                   pile  time using the --with-port option.  If the --with-uds
196                   option was used, this option is ignored.
197
198       -Ppasswd    Read the table  of  authorized  user  data  from  the  file
199                   passwd.   The default passwd may be changed at compile time
200                   using the --with-pwdfile option.
201
202       -R          Disable automatic client  redirection  to  other  conserver
203                   hosts.   This  means  informational commands like -w and -i
204                   will only show the status of the local conserver  host  and
205                   attempts  to  connect  to remote consoles will result in an
206                   informative message to the user.
207
208       -S          Do not run the server, just perform a syntax check of  con‐
209                   figuration  file and exit with a non-zero value if there is
210                   an error.  Using more than one -S will cause  conserver  to
211                   output  various  information about each console in 5 colon-
212                   separated fields, enclosed in curly-braces.  The philosophy
213                   behind the output is to provide information to allow exter‐
214                   nal detection of multiple consoles access the same physical
215                   port.  Since this is highly environment-specific, conserver
216                   cannot do the check internally.
217
218                   name     The name of the console.
219
220                   master   The hostname of the master conserver host for  the
221                            console.
222
223                   aliases  The console aliases in a comma-separated list.
224
225                   type     The  type  of console.  Values will be a `/' for a
226                            local device, `|' for a command, `!' for a  remote
227                            port,  `%' for a Unix domain socket, and `#' for a
228                            noop console.
229
230                   details  Multiple values are comma-separated and depend  on
231                            the  type of the console.  Local devices will have
232                            the values of the device file and  baud  rate/par‐
233                            ity.  Commands will have string to invoke.  Remote
234                            ports will have the values of the remote  hostname
235                            and  port  number.   Unix domain sockets will have
236                            the path to the socket.  Noop consoles  will  have
237                            nothing.
238
239       -u          Send  unloved  console output to conserver's stdout (which,
240                   in daemon  mode,  is  redirected  to  the  logfile).   This
241                   applies to all consoles to which no user is attached, inde‐
242                   pendent  of  whether  logging  of  individual  consoles  is
243                   enabled via conserver.cf entries.
244
245       -Ulogfile   Copy all console data to the ``unified'' logfile.  The out‐
246                   put is the same as the -u output,  but  all  consoles,  not
247                   just those without a user, are logged.  Each line of output
248                   is prefixed with the console name.  If a user  is  attached
249                   read/write, a `*' is appended to the console name, to allow
250                   log watching utilites to ignore  potential  user-introduced
251                   alarms.
252
253       -v          Echo the configuration as it is being read (be verbose).
254
255       -V          Output  the  version  number  and settings of the conserver
256                   program and then exit.
257

PROTOCOL

259       The protocol used to interact with the conserver daemon has  two  basic
260       styles.   The  first style is the initial line-based mode, which occurs
261       before connecting to a console.  The second  style  is  the  character-
262       based, escape-sequence mode, while connected to a console.
263
264       The initial line-based mode begins the same for both the master process
265       and its children.  Upon a successful (non-rejected) client  connection,
266       an  ``ok''  is  sent.   The client then issues a command and the server
267       responds to it with a result string (``ok'' being the sign  of  success
268       for  most  commands).  The commands available are ``help'', ``ssl'' (if
269       SSL was built into the  code),  ``login'',  and  ``exit''.   Using  the
270       ``login''  command,  the  client  authenticates and gains access to the
271       extended command set.  This is where the master process and  its  chil‐
272       dren differ.  The master process gives the client access to global com‐
273       mands, and the child provides commands for interacting  with  the  con‐
274       soles  it manages.  The ``help'' command, in both cases, will provide a
275       complete list of commands and a short description of what they do.
276
277       The second, character-based,  style  of  interaction  occurs  when  the
278       client  issues the ``call'' command with a child process.  This command
279       connects the client to a console and, at that point, relays all traffic
280       between  the  client  and  the console.  There is no more command-based
281       interaction between the client and the server, any interaction with the
282       server is done with the default escape sequence.
283
284       This   is,   by   no  means,  a  complete  description  of  the  entire
285       client/server interaction.  It is,  however,  a  brief  explanation  in
286       order  to  give a idea of what the program does.  See the PROTOCOL file
287       in the distribution for further details.
288

FILES

290       The following default file locations may be overridden at compile  time
291       or  by  the  command-line options described above.  Run conserver -V to
292       see the defaults set at compile time.
293
294       /etc/conserver.cf        description  of  console  terminal  lines  and
295                                client    host   access   levels;   see   con‐
296                                server.cf(5).
297       /etc/conserver.passwd    users allowed to  access  consoles;  see  con‐
298                                server.passwd(5).
299       /var/run/conserver.pid   the master conserver process ID
300       /var/log/conserver       log of errors and informational messages
301       /tmp/conserver           directory  to  hold  Unix  domain  sockets (if
302                                enabled)
303
304       Additionally, output from individual consoles may be logged to separate
305       files specified in conserver.cf(5).
306

BUGS

308       I'm  sure there are bugs, I just don't know where they are.  Please let
309       me know if you find any.
310

AUTHORS

312       Thomas A. Fine, Ohio State Computer Science
313       Kevin S Braunsdorf, Purdue University Computing Center
314       Bryan Stansell, conserver.com
315

SEE ALSO

317       console(1), conserver.cf(5), conserver.passwd(5)
318
319
320
321conserver-8.2.1                   2006/12/31                      CONSERVER(8)
Impressum