    New console I/O infrastructure in Xen 1.3
    =========================================

    Keir Fraser, University of Cambridge, 3rd June 2004

 I thought I'd write a quick note about using the new console I/O
 infrastructure in Xen 1.3. Significant new features compared with 1.2,
 and with older revisions of 1.3, include:
  - bi-directional console access
  - log in to a Xenolinux guest OS via its virtual console
  - a new terminal client (replaces the use of telnet in character mode)
  - proper handling of terminal emulation

Accessing the virtual console from within the guest OS
------------------------------------------------------
 Every Xenolinux instance owns a bidirectional 'virtual console'.
 The device node to which this console is attached can be configured
 by specifying 'xencons=' on the OS command line:
  'xencons=off'  --> disable virtual console
  'xencons=tty'  --> attach console to /dev/tty1 (tty0 at boot-time)
  'xencons=ttyS' --> attach console to /dev/ttyS0
 The default is to attach to /dev/tty1, and also to create dummy
 devices for /dev/tty2-63 to avoid warnings from many standard distro
 startup scripts. The exception is domain 0, which by default attaches
 to /dev/ttyS0.

Domain 0 virtual console
------------------------
 The virtual console for domain 0 is shared with Xen's console. For
 example, if you specify 'console=com1' as a boot parameter to Xen,
 then domain 0 will have bi-directional access to the primary serial
 line. Boot-time messages can be directed to the virtual console by
 specifying 'console=ttyS0' as a boot parameter to Xenolinux.

Connecting to the virtual console
---------------------------------
 Domain 0 console may be accessed using the supplied 'miniterm' program
 if raw serial access is desired. If the Xen machine is connected to a
 serial-port server, then the supplied 'xencons' program may be used to
 connect to the appropriate TCP port on the server:
  # xencons <server host> <server port>

Logging in via virtual console
------------------------------
 It is possible to log in to a guest OS via its virtual console if a
 'getty' is running. In most domains the virtual console is named tty1
 so standard startup scripts and /etc/inittab should work
 fine. Furthermore, tty2-63 are created as dummy console devices to
 suppress warnings from standard startup scripts. If the OS has
 attached the virtual console to /dev/ttyS0 then you will need to
 start a 'mingetty' on that device node.

Virtual console for other domains
---------------------------------
 Every guest OS has a virtual console that is accessible via
 'console=tty0' at boot time (or 'console=xencons0' for domain 0), and
 mingetty running on /dev/tty1 (or /dev/xen/cons for domain 0).
 However, domains other than domain 0 do not have access to the
 physical serial line. Instead, their console data is sent to and from
 a control daemon running in domain 0. When properly installed, this
 daemon can be started from the init scripts (e.g., rc.local):
  # /usr/sbin/xend start

 Alternatively, Redhat- and LSB-compatible Linux installations can use
 the provided init.d script. To integrate startup and shutdown of xend
 in such a system, you will need to run a few configuration commands:
  # chkconfig --add xend
  # chkconfig --level 35 xend on
  # chkconfig --level 01246 xend off
 This will avoid the need to run xend manually from rc.local, for example.

 Note that, when a domain is created using xc_dom_create.py, xend MUST
 be running. If everything is set up correctly then xc_dom_create will
 print the local TCP port to which you should connect to perform
 console I/O. A suitable console client is provided by the Python
 module xenctl.console_client: running this module from the command
 line with <host> and <port> parameters will start a terminal
 session. This module is also installed as /usr/bin/xencons, from a
 copy in tools/misc/xencons. For example:
  # xencons localhost 9600

 An alternative to manually running a terminal client is to specify
 '-c' to xc_dom_create.py, or add 'auto_console=True' to the defaults
 file. This will cause xc_dom_create.py to automatically become the
 console terminal after starting the domain.
