Blame - conmux/conmux.html - platform/external/autotest

blob: 9f9cbeaf3184e73bb8a5ea5a3957cc14e26eff59 [file] [log] [blame]

apw	3812c03	2006-12-07 21:01:14 +0000	[diff] [blame]	1	<html>
				2	<!--
				3	# (C) Copyright IBM Corp. 2004, 2005, 2006
				4	# Author: Andy Whitcroft <andyw@uk.ibm.com>
				5	#
				6	# The Console Multiplexor is released under the GNU Public License V2
				7	-->
				8	<head>
				9	<title>conmux - the console multiplexor</title>
				10	<style type="text/css">
				11	.example { white-space: pre; margin-left: 2em; margin-right: 2em;
				12	font-family: monospace }
				13	table.quote { margin-left: 2em; margin-right: 2em }
				14	</style>
				15	</head>
				16
				17	<body>
				18	<center>
				19	<h1>conmux - the console multiplexor</h1>
				20	</center>
				21
				22	<p><em>conmux</em>, the console multiplexor is a system designed to abstract
				23	the concept of a console. That is to provide a virtualised machine interface,
				24	including access to the console and the 'switches' on the front panel; the
				25	/dev/console stream and the reset button. It creates the concept of a virtual
				26	console server for multiple consoles and provides access to and sharing of
				27	consoles connected to it.
				28
				29	<p>There are two main motivations for wanting to do this. Firstly, we have
				30	many different machine types with vastly differing access methodologies for
				31	their consoles and for control functions (VCS, HMC, Annex) and we neither want
				32	to know what they are nor how they function. Secondly, most console sources
				33	are single access only and we would like to be able to share the console data
				34	between many consumers including users.
				35
				36	<h2>Basic Usage</h2>
				37
				38	<p>The main interface to the consoles is via the <code>console</code>
				39	program. This connects us to the console server for the machine and allows us
				40	to interact with it, including issuing <i>out-of-band</i> commands to control
				41	the machine.
				42
				43	<div class="example">$ console <host>/<console>
				44	</div>
				45
				46	<p>In the example below we indicate that the console we require is located on
				47	the virtual console server <code>consoles.here.com</code> and the
				48	specific console is <code>elm3b70</code>.
				49
				50	<div class="example">$ console consoles.here.com/elm3b70
				51	Connected to elm3b70 console (~$quit to exit)
				52
				53	Debian GNU/Linux 3.1 elm3b70 ttyS0
				54
				55	elm3b70 login:
				56	</div>
				57
				58	<p>Once connected we can interact normally with the console stream. To
				59	perform front pannel operation such as peforming an <em>hard reset</em> we
				60	switch to command mode. This is achieved using the escape sequence
				61	<code>~$</code>. Nore the prompt <code>Command></code>
				62
				63	<div class="example">elm3b70 login: <em>~$</em>
				64	Command> quit
				65	Connection closed
				66	$
				67	</div>
				68
				69	<h2>Command Summary</h2>
				70
				71	<p>The following commands are generally available:
				72
				73	<p><table class="quote" rules="all" frame="box">
				74
				75	<tr><th>Command<th>Description</tr>
				76
				77	<tr><td>quit<td>quit this console session, note that this disconnects us from
				78	the session it does not affect the integity of the session itself.</tr>
				79
				80	<tr><td>hardreset<td>force a hard reset on the machine, this may be a simple
				81	reset or a power off/on sequence whatever is required by this system.</tr>
				82
				83	</table>
				84
				85	<h2>Architecture</h2>
				86
				87	<p>The conmux provides a virtual console multiplexor system reminicent of
				88	an Annex terminal server. You refer to the conmux <em>server</em> and
				89	<em>lines</em>, unlike an Annex lines are referred to by mnemonic names.
				90	Above we referred to the console for <code>elm3b70</code> 'connected to' the
				91	server <code>consoles.here.com</cond>. A virtual console server consists
				92	of a number of server processes. One <code>conmux-registry</code> server,
				93	several <code>conmux</code> servers and optionally several <em>helper</em>
				94	processes.
				95
				96	<p><code>conmux-registry</code>: a server is defined by the server registry.
				97	This maintains the mnemonic name to current server location relation. When
				98	a client wishes to attach to a console on a server, the registry is first
				99	queried to locate the server currently handling that console.
				100
				101	<p><code>conmux</code>: for each connected console there is a corresponding
				102	console multiplexor. This process is responsible for maintaining the
				103	connection to the console and for redistributing the output to the various
				104	connected clients. It is also responsible for handling "panel" commands
				105	from the client channels.
				106
				107	<p><code>autoboot-helper</code>: an example helper which aids systems which
				108	are not capable of an automatic reboot. It connects to a console and watches
				109	for tell-tale reboot activity, preforming a "panel" <em>hardreset</em> when
				110	required. This provides the impression of seamless reboot for systems
				111	which this does not work.
				112
				113	<h2>Configuration</h2>
				114
				115	<h3>conmux-registry</h3>
				116
				117	<p>Configuration of this service is very simple. Supplying the default
				118	registry port (normally 63000) and the location for the persistant registry
				119	database.
				120
				121	<h3>conmux</h3>
				122
				123	<p>Configuration of each conmux is complex. Each has a listener, payload
				124	and optionally one or more panel commands. Configuration is provided via
				125	a per console configuration file. This file consists of lines defining each
				126	element:
				127
				128	<p><code>listener <server>/<name></code>:
				129	defines the name of this console port as it appears in the registry.
				130
				131	<p><code>socket <name> <title> <host>:<port></code>:
				132	defines a console payload connected to a tcp socket on the network.
				133	<code>name</code> defines this payload within the multiplexor,
				134	<code>title</code> is announced to the connecting clients.
				135
				136	<p><code>application <name> <title> <cmd></code>:
				137	defines a console payload which is accessed by running a specific command.
				138	<code>name</code> defines this payload within the multiplexor,
				139	<code>title</code> is announced to the connecting clients.
				140
				141	<p><code>command <panel> <message> <cmd></code>:
				142	defines a panel command for the preceeding payload, triggerd when
				143	<code>panel</code> is typed at the command prompt. <code>message</code>
				144	is announced to the user community. <code>cmd</cmd> will be actually
				145	executed.
				146
				147	<p>For example here is the configuration for a NUMA-Q system which is rebooted
				148	using a remote VCS console and for which the real console channel is
				149	on an Annex terminal server:
				150
				151	<div class="example">listener localhost/elm3b130
				152	socket console 'elm3b130 console' console.server.here.com:2040
				153	command 'hardreset' 'initated a hard reset' \
				154	'./reboot-numaq vcs 1.2.3.4 elm3b130 12346 Administrator password'
				155	</div>
				156
				157	</body>
				158	</html>