docs/system/s390x/3270.rst

   1 3270 devices
   2 ============
   3
   4 The 3270 is the classic 'green-screen' console of the mainframes (see the
   5 `IBM 3270 Wikipedia article <https://en.wikipedia.org/wiki/IBM_3270>`__).
   6
   7 The 3270 data stream is not implemented within QEMU; the device only provides
   8 TN3270 (a telnet extension; see `RFC 854 <https://tools.ietf.org/html/rfc854>`__
   9 and `RFC 1576 <https://tools.ietf.org/html/rfc1576>`__) and leaves the heavy
  10 lifting to an external 3270 terminal emulator (such as ``x3270``) to make a
  11 single 3270 device available to a guest. Note that this supports basic
  12 features only.
  13
  14 To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to
  15 a ``tn3270`` chardev. The guest will see a 3270 channel device. In order
  16 to actually be able to use it, attach the ``x3270`` emulator to the chardev.
  17
  18 Example configuration
  19 ---------------------
  20
  21 * Make sure that 3270 support is enabled in the guest's Linux kernel. You need
  22   ``CONFIG_TN3270`` and at least one of ``CONFIG_TN3270_TTY`` (for additional
  23   ttys) or ``CONFIG_TN3270_CONSOLE`` (for a 3270 console).
  24
  25 * Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command line::
  26
  27    -chardev socket,id=ch0,host=0.0.0.0,port=2300,wait=off,server=on,tn3270=on
  28    -device x-terminal3270,chardev=ch0,devno=fe.0.000a,id=terminal0
  29
  30 * Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable
  31   the device.
  32
  33 * On the host, start the ``x3270`` emulator::
  34
  35     x3270 <host>:2300
  36
  37 * In the guest, locate the 3270 device node under ``/dev/3270/`` (say,
  38   ``tty1``) and start a getty on it::
  39
  40     systemctl start serial-getty@3270-tty1.service
  41
  42   This should get you an additional tty for logging into the guest.
  43
  44 * If you want to use the 3270 device as the Linux kernel console instead of
  45   an additional tty, you can also append ``conmode=3270 condev=000a`` to
  46   the guest's kernel command line. The kernel then should use the 3270 as
  47   console after the next boot.
  48
  49 Restrictions
  50 ------------
  51
  52 3270 support is very basic. In particular:
  53
  54 * Only one 3270 device is supported.
  55
  56 * It has only been tested with Linux guests and the x3270 emulator.
  57
  58 * TLS/SSL is not supported.
  59
  60 * Resizing on reattach is not supported.
  61
  62 * Multiple commands in one inbound buffer (for example, when the reset key
  63   is pressed while the network is slow) are not supported.