1CONSERVER(8) conserver CONSERVER(8)
2
6 conserver - console server daemon
7
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
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 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 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 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 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 SIGTERM Close all connections and exit.
67 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 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 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 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 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 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
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 -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 -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 -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 -ccred Load an SSL certificate and key from the PEM encoded file
131 cred.
132 -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 -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 -D Enable debugging output, sent to stderr. Multiple -D op‐
142 tions increases debug output.
143 -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 -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 -h Output a brief help message.
158 -i Initiate console connections on demand (and close them when
160 not used).
161 -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 -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 -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 -n Obsolete (now a no-op); see -u.
181 -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 -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 -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 -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 -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 -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 name The name of the console.
219 master The hostname of the master conserver host for the
221 console.
222 aliases The console aliases in a comma-separated list.
224 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 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 -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 -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 -v Echo the configuration as it is being read (be verbose).
254 -V Output the version number and settings of the conserver
256 program and then exit.
257
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 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 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 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
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 /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 Additionally, output from individual consoles may be logged to separate
305 files specified in conserver.cf(5).
306
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
312 Thomas A. Fine, Ohio State Computer Science
313 Kevin S Braunsdorf, Purdue University Computing Center
314 Bryan Stansell, conserver.com
315
317 console(1), conserver.cf(5), conserver.passwd(5)
318conserver-8.2.7 2022/07/07 CONSERVER(8)