insert new diagram, flesh out API, add a few questions..

lab.doc.md.html

@@ -25,7 +25,7 @@ images on various boards remotely.
 - Long term goals:
   - Emulated microSD cards
 
-### Architecture
+### Physical Architecture
 
 The following diagrams the connections between the components.  It is expected
 that the connections for the RockPro64 is followed similarly for other embedded
@@ -42,29 +42,101 @@ The PoE part of the switch will be used for power control.  PoE splitters (~$10)
 are readily available and inexpensive, and the cost per port is realatively
 inexpensive considering that power consumption will also be provided.
 
-***********************************************************************************
-*                                                                                 *
-* +--------------+                                            +-----------------+ *
-* | Host machine +-----------------------------------------+  |    Internet     | *
-* +-+------------+                                         |  +-+---------------+ *
-*   |                                                      |    |                 *
-*   |                                                      |    |                 *
-*   |                                                      |    |                 *
-* +-+------------+     +----------------+                  |  +-+---------------+ *
-* |   USB Hub    +-----+ Serial adapter |                  +--+ PoE/VLAN Switch | *
-* +--------------+     +-+--------------+                     +-+---------------+ *
-*                        |                                      |                 *
-*                        |                                      |                 *
-*                        |                                      |                 *
-*                      +-+--------------+      Network        +-+---------------+ *
-*                      |   RockPro64    +---------------------+  PoE Splitter   | *
-*                      +-+--------------+                     +-+---------------+ *
-*                        |                                      |                 *
-*                        |                                      |                 *
-*                        |                                      |                 *
-*                       Power                                   |                 *
-*                      -----------------------------------------+                 *
-*                                                                                 *
-***********************************************************************************
+**************************************************************************
+*                                                                        *
+* +--------------+                                   +-----------------+ *
+* | Host machine +-------------------------+         |    Internet     | *
+* +-+------------+                         |         +-+---------------+ *
+*   |                                      |           |                 *
+*   |                                      |           |                 *
+*   |                                      |           |                 *
+* +-+------------+     +----------------+  |         +-+---------------+ *
+* |   USB Hub    +-----+ Serial adapter |  +---------+ PoE/VLAN Switch | *
+* +--------------+     +-+--------------+            +-+---------------+ *
+*                        |                             |                 *
+*                        |                             |                 *
+*                        |                             |                 *
+*                      +-+--------------+  Network   +-+---------------+ *
+*                      |   RockPro64    +------------+  PoE Splitter   | *
+*                      +-+--------------+            +-+---------------+ *
+*                        |                Power        |                 *
+*                        +-----------------------------+                 *
+*                                                                        *
+**************************************************************************
+
+### Logical Architecture
+
+No user will be able to log into the host machine directly.  The only user
+interface exposed on the host will be via an RPC interface, e.g.
+`echo function xxx | ssh labhost labcli`, or via a socket from within
+the jail.
+
+Workflow
+--------
+
+# Functions
+
+The functions that take a device handle can be executed from within the device jail
+and the device handle of that device jail will be used.  An error will be raised if
+a device handle is provided and it does not match the current jail.
+
+These are the functions a user can execute:
+1. List device classes (onlyavailable=false)
+   List the device classes that are known about.  If onlyavailable is true, than only
+   ones that are currently available for claiming are returned.
+2. Device status (claimed=false)
+   List all the device statuses currently.  This includes that status, claimed or
+   unclaimed.  If the device is claimed, it includes the user to claimed it.  If claimed
+   is true, only list devices that are currently claimed by you.  The default is to list
+   all devices.
+3. Claim device (device class, power=false)
+   A user can use this to lock a device.  This will return a device handle with the
+   device information, such as the device's jail's IP address, or an error.  Once they
+   have obtained a device, it will not be allocated to another user till they have release
+   this device (or in the future a timeout has been hit).  The user's ssh keys will be
+   automatically populated in that jail.  By default, the device will be in the power off
+   state.  When a default configuration is provided for the board, it can be automatically
+   powered on to make it easier to integrate w/ systems like CI.
+4. Reinit device (device handle)
+   This will remove the current jail, and recreate it as if it was claimed for the first
+   time.  This can be done so you can get the jail in a clean state w/o risk losing the
+   lock by freeing it and then reclaiming it.  If you have not claimed the device, an
+   error will be returned.  If the reinit fails, an error will be returned, but the claim
+   will be maintained.
+5. Release device (device handle)
+   Release a claim on the device handle returned by claim device.  This will make it
+   available to users again.  All data in the jail will be deleted.  It will return an
+   error if you do have have a claim on the device.
+6. Power off (device handle)
+   Turn off the power to the device.
+7. Power on (device handle)
+   Turn on the power to the device.
+
+# Services provided in the device jail
+
+Once logged in, the jail will have the following services:
+1. ssh
+   Incoming ssh must be provided for the user to login.
+2. One interface for internet
+   nat setup so that all traffic appears from jail's IP.
+3. One interface for device
+4. Serial port for console access
+5. dhcpd for device w/ tftp already configured
+6. inetd w/ tftpd setup
+7. nfsd setup w/ exports configured
+8. power control for device
+
+As the user will have root access, all of these can be modified after.
+
+Questions
+=========
+
+Should the host key for the device be kept between invocations.
+Pros: Users don't have to munch the known_hosts every time.
+Cons: Malicious user could impersonate the jail as they can copy out the key.
+
+IPv6 support?
+	I have enough that each device can get a /64, but this remove privacy in
+	that the network will tell which device was active at the time
 
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>