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 pa‐
22       rameters,  and user access levels are just a few of the things that can
23       be specified.  Command-line options are then applied, possibly overrid‐
24       ing  conserver.cf(5) settings.  Conserver categorizes consoles into two
25       types: those it should actively manage, and those it should  just  know
26       about,  so  it  can refer clients to other conserver instances.  If the
27       master value of a console matches the hostname or ip address of the lo‐
28       cal  machine,  conserver  will actively manage the console.  Otherwise,
29       it's considered a ``remote'' console and managed by a different server.
30       Conserver  forks  a child for each group of consoles it must manage and
31       assigns each process a port number to listen on.  The maximum number of
32       consoles managed by each child process is set using the -m option.  The
33       console(1) client program communicates with the master  console  server
34       process to find the port (and host, in a multi-server configuration) on
35       which the appropriate child is listening.  Conserver restricts  connec‐
36       tions  from  clients  based  on  the  host  access  section of its con‐
37       server.cf(5) file, restricts users based on the console access lists of
38       the  conserver.cf(5)  file,  and  authenticates  users against its con‐
39       server.passwd(5) file.  Conserver can also restrict clients  using  the
40       tcp-wrappers  package (enabled using --with-libwrap).  This authentica‐
41       tion is done before consulting the conserver.cf(5) access list.
42
43       When Unix domain sockets are used between the client  and  server  (en‐
44       abled  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 di‐
50       rectory  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  se‐
60       quences.
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 ac‐
83                 tions 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 al‐
119                   lowed, or `t' for trusted.  This applies to hosts for which
120                   no matching entry is found in the access  section  of  con‐
121                   server.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 op‐
128                   erating 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 op‐
142                   tions 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  en‐
147                   crypted 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  op‐
153                   tion, a console is immediately reopened, and if that fails,
154                   retried every minute until successful.  This option has  no
155                   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  ap‐
241                   plies  to  all consoles to which no user is attached, inde‐
242                   pendent of whether logging of individual  consoles  is  en‐
243                   abled 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 utilities 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 re‐
267       sponds to it with a result string (``ok'' being the sign of success for
268       most  commands).   The commands available are ``help'', ``ssl'' (if SSL
269       was built into the code), ``login'', and ``exit''.  Using the ``login''
270       command, the client authenticates and gains access to the extended com‐
271       mand set.  This is where the master process and  its  children  differ.
272       The  master process gives the client access to global commands, and the
273       child provides commands for interacting with the consoles  it  manages.
274       The  ``help''  command,  in both cases, will provide a complete list of
275       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 in‐
281       teraction 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  or‐
286       der  to give a idea of what the program does.  See the PROTOCOL file in
287       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 en‐
302                                abled)
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.6                   2020/10/19                      CONSERVER(8)
Impressum