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
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 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 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 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
83 actions 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
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 -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 -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
142 options 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
147 encrypted 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
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 -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
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 -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 -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
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 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 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
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
302 enabled)
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.1.16 2006/12/31 CONSERVER(8)