DreamboxPlugin
--------------

Plugin for automatic monitoring and remote maintenance of dreamboxes (or any other linux-based STB).
This plugin is experimental and unfinished, it doesn't do much unless extended further.
It requires a remote agent running on the box (included as part of this plugin) and uses a separate httpd that the
agent will periodically report to. It gives the proxy admin potentially limitless control over the box, so it can
only be used where the users fully trusts the admin.

The remote agent is made up entirely of shell scripts (busybox builtin ash compatible), and works as follows:
- User installs the agent via an install script retrieved from the plugin httpd.
  I.e: User runs wget from /tmp/ to fetch http://user:passwd@proxy-host:plugin-httpd-port/installer.sh
  then executes the installer (chmod +x installer.sh; ./installer.sh).
- The installer will find a method for auto-starting the agent that works on any box (hopefully), and launch it.
- The agent will connect back to the plugin-httpd and perform a login, by sending various custom http headers.
- If the login succeeds the response will be a generated hash id that will identify this box from now on.
- The agent will then report back to the plugin-httpd every 5 minutes, checking for further instructions and
  reporting various usage stats.
- If the plugin has a task to run, the periodic check-in will result in downloading and executing more ash
  scripting generated by the plugin, allowing the proxy admin to perform any task locally on the box.
  The output resulting from the script is returned to the plugin (using a telnet pipe to do a http connect operation).
  This allows the proxy admin to perform lengthy/continous tasks (i.e tail a logfile, run dvbsnoop).
  NOTE: If an image doesn't have a telnet applet in busybox nc will be tried instead. If neither exist, the agent will
  not work (of course actual telnet/nc binaries may do the trick, and could be installed if there is room).
- Tasks (ash scripts) are placed either within the dreamboxplugin.jar under web/open/scripts or in the directory that
  the plugin creates (dreamboxplugin/scripts). Both locations are checked and the resulting list merged for the web ui.
  The included dreamboxplugin/scripts/test.sh script shows which substitution variables are available to scripters.
  
Once a box is running the agent, the plugin will connect the box identity with any existing newcamd sessions.
It will do this by proxy username alone for now, so there is no protection against abuse by users spoofing.

The plugin also has the option of running an embedded sshd (separate from whatever other sshd the system may have).
This is intended to be used mainly for port-fowarding, i.e having agent-scripts use dropbear to create reverse ssh
tunnels that lead back to the box through a port opened by the plugin on the proxy server. This way the admin could
log into individual boxes at will even though they're behind firewall/nat.

Enabling the sshd will show a custom script (ssh_tunnel.sh) for deploying dropbear and starting a reverse tunnel.
To do this, dropbear binaries first have to be placed in dreamboxplugin/binaries/ and they have to be specific versions
in order to run on as many boxes as possible. A dreamboxplugin/fetch_binaries.sh script exists to automatically install
a combination of ppc and mips dropbear binaries that have been found to work well (and are available precompiled in
public repositories). The dreamboxplugin dir tree is created by the plugin when it is first loaded.

NOTE: 
- The idea with the agent is to create something that relies only on busybox features already present on all
  boxes, avoiding extra binaries that would need to be cross-compiled and maintained. The full list of used
  busybox applets is: ash (i.e /bin/sh), wget, telnet, date, ps, grep, sed, expr
- This approach with periodic checks is used to avoid having each box maintain an extra open connection with
  the proxy (it already has at least one for newcamd). It also means the box doesn't have to open up any
  firewalls to let the proxy plugin in, all connections are outgoing from box to plugin.
- The reason for the separate httpd is simply to allow the regular proxy httpd to use ssl, which wouldn't
  work with busybox builtin wget.

- The file upload support is actually just redirecting command output to a preconfigured server side file, so to
  "interactively" fetch for example a e2 services file, you'd run "cat /etc/enigma2/lamedb" with the file arg set to
  lamedb (and a file upload entry configured for the user that tells the plugin where to put output matching the name
  lamedb - if it exists it will be overwritten).
  The uploading is unsecured, anyone who has access to the box will be able to overwrite the preconfigured target-path
  on the server side. Boxes can also perform unsolicited/scheduled uploads without any associated dbplugin command.
  NOTE: Requesting uploads in the web ui (by selecting a file name after >) will only apply to boxes registered to the
  user that has the upload permissions. This is then indicated by a "> f" suffix to the pending operation name.

- Since the addition of the sshd, the plugin has the following dependencies (fetched automatically at runtime, but
  necessary for compiling the plugin - place them in lib/):

  http://repo1.maven.org/maven2/org/apache/sshd/sshd-core/0.3.0/sshd-core-0.3.0.jar
  http://repo1.maven.org/maven2/org/apache/mina/mina-core/2.0.0-M6/mina-core-2.0.0-M6.jar
  http://repo2.maven.org/maven2/org/slf4j/slf4j-api/1.5.2/slf4j-api-1.5.2.jar
  http://repo2.maven.org/maven2/org/slf4j/slf4j-jdk14/1.5.2/slf4j-jdk14-1.5.2.jar

TODO/SUGGESTIONS:
- Determine which boxes/images the agent and installer scripts work on and extend support to cover additional ones.
- Extend the repository of scripts that can be remote executed by admin on any box running the agent via the plugin web.
- Add more binaries (dvbsnoop!)
- Create alternate installation methods for the agent (e.g a nsis windows installer).

Example config:
---------------
  <plugin class="com.bowman.cardserv.DreamboxPlugin" enabled="false" jar-file="dreamboxplugin.jar">
    <plugin-config>         
    
      <check-interval>5</check-interval> <!-- the starting interval downloaded installers will be configured for -->

      <agent-web> 
        <listen-port>8083</listen-port>
        <frontend-host>proxy1.host.com</frontend-host> <!-- external hostname boxes will be accessing via -->
        <frontend-port>8083</frontend-port> <!-- external port (remove to use same as listen port) -->
        <log-file rotate-count="5" rotate-max-size="2048">log/agent-web-access.log</log-file> <!-- remove to disable -->
                
        <alternative-connect>false</alternative-connect> 
        <!-- if true: use XCNT instead of CONNECT, to avoid anti-abuse/open-proxy-scan blocks (if certain boxes never get output through) -->
      </agent-web>

      <agent-sshd enabled="false"> <!-- starting the sshd requires java6 or newer -->
        <listen-port>2222</listen-port>
        <tunnel-port-range start="2323" count="10"/> <!-- allow clients to open remote tunnel endpoints for these ports -->
      </agent-sshd>

      <file-upload enabled="true"> <!-- allow certain users to upload files, but only to preconfigured locations -->
        <file name="links.cfg" target-path="etc/links.cfg" user="linkslave"/>
        <file name="lamedb" target-path="etc/services.someuser.e2" user="someuser"/>
        <file name="lamedb" target-path="etc/services.otheruser.e2" user="otheruser"/>
        <file name="ecm.info" target-path="/tmp/" user="testuser"/>
        <!-- if target-path is a dir the provided file name will be appended, e.g /tmp/ecm.info -->
      </file-upload>
      
    </plugin-config>
  </plugin>
  
Status commands:
----------------
- list-boxes: Show all known boxes.
    optional parameters: hide-inactive (true/false, exclude boxes that haven't checked in for > interval*2).
- box-details: Show details for selected box
    mandatory parameters: id (the id hash for the box to view, e.g: 4b5899796ec1fb4b4332c52b66f4a6039792b467)

Ctrl commands:
--------------
- delete-box: Remove specified box from the registry.
    mandatory parameters: id (the id hash for the box to delete)
- close-tunnel: Close any open ssh tunnel for the specified box.
    mandatory parameters: id (the id hash for the box to close tunnels for)
- abort-operation: Abort a pending or running operation.
    mandatory parameters: id (the id hash for the box)
                          op (operation number, only applicable for running operations)

Usage example
-------------
http://proxy.host.com/xmlHandler?command=list-boxes&hide-inactive=false



  
                             
