From 3934030af1b7bf4d4ec7ba48219c950195ddd3c9 Mon Sep 17 00:00:00 2001
From: John-Mark Gurney <jmg@funkthat.com>
Date: Fri, 5 Mar 2021 11:34:52 -0800
Subject: [PATCH] flesh out the docs for this a little bit.  There is still a
 lot more to write..

---
 README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/README.md b/README.md
index 2cc346e..45000f5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,108 @@
 BITELAB
 =======
 
+Bitelab is the server and client portions implemented for a fully
+remote controlled lab, allowing for each board to have a different
+set of attributes, which are for things like power control and
+network access.  This means that the board's power can be controlled
+via different methods, such as GPIO (not implemented yet) or SNMP
+control of PoE switches.
+
+This repository is both the client and the server for the bitelab
+infrastructure.
+
+Features:
+- Tunneling of ssh over HTTP(S), allowing only the HTTP endpoint
+  to be exposed publicly, making deployment significantly easier.
+- UCL for configuration of boards
+
+Client
+------
+
+The client expects two environment variables to be set, BITELAB_URL
+and BITELAB_AUTH.  The BITELAB_URL is set to the base URL of the
+Bitelab API.  The BITELAB_AUTH is set to the authentication token.
+To get an auth token, use the command:
+```
+ssh -o 'ProxyCommand bitelab contssh' -l lab bitelab
+```
+
+The last argument, `bitelab` is not important, just should be unique
+from other labs, and consistent.
+
+The client provides basic commands to talk to the API.  The
+
+Server
+------
+
+The server uses a local configuration file, `.env`.  And example file
+is:
+```
+db_file=/ztank/state/bitelab.sqlite
+board_conf=/ztank/prog/board_conf.ucl
+```
+
+The `db_file` entry is used for recording state, but it is also
+contains the hashed access tokens to grant access to the boards.
+
+The `board_conf` entry is a pointer to a UCL file that defines all
+the boards that are supported by the system.  An example file is:
+```
+setup_script = /ztank/prog/board_script;
+
+classes {
+        cora-z7s = { arch = arm-armv7; }
+        pine64-a64-lts = { arch = arm64-aarch64; }
+}
+
+boards [
+        {
+                name = cora-1;
+                brdclass = cora-z7s;
+                options = [
+                        { cls = snmppower, host = poe, port = 2 },
+                ]
+        },
+        {
+                name = a64lts-1;
+                brdclass = pine64-a64-lts;
+                options = [
+                        { cls = etheriface, val = awg0.103 },
+                        { cls = serialconsole, val = /dev/ttyU0 },
+                        { cls = snmppower, host = poe, port = 3 },
+                ]
+        },
+]
+```
+
+The `setup_script` is run when a board is reserved or released.  This
+contains the logic to setup/destroy the file system for the jail,
+start/terminate the jail and reserve and release resources such as the
+IP address for the jail.
+
+The `classes` object contains entires for each class of board.  This
+contains the common parameters for boards that are the same.  Boards
+in a class should be the same so that a user can check out a class,
+and get a board that matches their needs.  This allows adding multiple
+boards that are popular and allow automatic selection of an available
+board.
+
+The specific configuration for each board is in the list `boards`.
+Each board MUST have a `name` which needs to be unique, a `brdclass`
+to which the board belongs (from the previous `classes`), and an
+`options` list which contains the configuration of the board.
+
+Each option must have a `cls` parameter, which defines the behavior
+of the rest of the options.
+
+The following `cls` values are supported (see `_option_map` attribute
+of the class `BoardManager` in `bitelab/__init__.py`):
+- etheriface
+- serialconsole
+- snmppower
+
+The remaining items in the object are passed as key word arugments
+to the respective classes.
 
 NOTES
 =====