README

   1 NetWatch!
   2
   3 This is NetWatch, a system for remote system-management-mode-based control
   4 of a machine without support from or awareness by the OS.  It works by
   5 taking over a second network card to provide a standard VNC server, such
   6 that a machine elsewhere on the network can see the text or graphics console
   7 of the machine and inject keystrokes as needed.
   8
   9 System management mode, introduced with the 386SL, essentially allows system
  10 driver code to run outside of OS control, caused by a special interrupt pin
  11 on the CPU.  This was originally intended for applications such as laptop
  12 fan control; it is also the mechanism by which USB legacy keyboard emulation
  13 occurs.  When a system management interrupt occurs, the northbridge remaps
  14 portions of memory to expose previously-hidden code, and asserts an SMI#
  15 signal, causing the CPU to save all its state into system management RAM and
  16 vector to a magic entry point.
  17
  18 This is somewhat slow, and so there is a moderate performance impact caused
  19 by running NetWatch, more significant when a VNC session is open.  Because
  20 NetWatch is invisible to the OS, its CPU usage is difficult to monitor; we
  21 do so by comparing the MD5 throughput of the system with NetWatch running
  22 versus without.  The only way that the OS could detect this performance
  23 drain is by spinning tightly and watching for a sudden jump in the CPU's
  24 time stamp counters.
  25
  26 Although it would be possible to start up NetWatch after an OS kernel has
  27 already loaded, it is easier and more useful to load it from GRUB before the
  28 OS boots, such that even the bootloader itself can be controlled over the
  29 network.  We do this by providing a stub loader (grubload/) which can be
  30 invoked from GRUB, and takes care of loading the main NetWatch ELF image.
  31 Once this is done and NetWatch is up and running, the loader returns to real
  32 mode and reinvokes GRUB via the BIOS.
  33
  34 Our current development platform, the Intel ICH2, does not allow SMM traps
  35 on arbitrary PCI accesses.  This makes stealing the network card from the OS
  36 somewhat difficult, since there is nothing SMM code can do to cleanly block
  37 access.  NetWatch simply chooses its desired network card, and then
  38 repeatedly clobbers the PCI base address registers.  Although Linux resets
  39 the BARs to sane values when it probes the PCI bus, by the time it attempts
  40 to actually load the network driver, the card will no longer be accessible;
  41 fortunately, the driver quickly gives up, and Linux no longer attempts to
  42 access the card.
  43
  44 The northbridge can be configured to invoke a system management interrupt
  45 every 64 milliseconds, and so the bulk of NetWatch's work is done from this
  46 interrupt: checking the network card for incoming packets, invoking lwIP,
  47 and sending any response packets necessary.  SMM entry also occurs when when
  48 the OS reads from the keyboard I/O ports, to inject scan codes as needed.
  49
  50 Much of NetWatch is very hardware-dependent, and although we've tried to
  51 maintain clean interface separation to allow for easy porting, the current
  52 implementation requires:
  53
  54   * Intel ICH2 system chipset
  55   * 3C509 Ethernet card to be used by NetWatch, plus another card of
  56     any type for the OS
  57   * BIOS which does not set the D_LCK bit. Any system old enough to be
  58     based on the ICH2 is very likely to have a suitable BIOS.
  59
  60 Current open issues are listed in the TODO file. See GUIDE for an overview
  61 of which source files do what.