add reference docs for configuration options

docs/.wordlist.txt

@@ -4,38 +4,80 @@ APIs
 balancer
 CharmHub
 CLI
-dropdown
+CM3
+config
 Diátaxis
+distro
+dragonboard
+Dragonboard
+dropdown
+DUT
 EBS
+EFI
 EKS
+EMMC
 favicon
 Grafana
 IAM
+init
 installable
+Intel
 Jira
 JSON
 Juju
-Kubernetes
 Kubeflow
+Kubernetes
+logfile
+maas
+MaaS
+MAAS
 Makefile
+MUX
+muxpi
+MuxPi
 MyST
 namespace
 namespaces
+netboot
 NodePort
+noprovision
+NVidia
 observability
+OEM
+OEM
+oemrecovery
+oemscript
 OLM
 Permalink
+preloaded
+provisionable
+provisioner
 ReadMe
 readthedocs
 reST
 reStructuredText
 roadmap
+RPI
 RTD
+runtime
+SDWire
+SecureBoot
+SKU
 subdirectories
-subtree
 subfolders
+subtree
+templating
+Testflinger
+TPM
 txt
+ubuntu
+ubuntu
+ubuntu
+Ubuntu
 UI
+URI
+USB
 VM
 webhook
+xenial
 yaml

docs/reference/device-connector-conf.rst

@@ -0,0 +1,105 @@
+Device connector configuration options
+=======================================
+
+The configuration of a device connector contains details that are unique to this device, such as the IP address and environment data that should be used when running tests on this device.
+
+The device connector configuration is normally stored in a file called ``default.yaml`` in the source where the device connector runs.
+
+The configuration options listed below are available for all device connectors unless otherwise specified. For the list of supported types of device connectors, see :doc:`device-connector-types`.
+
+.. list-table:: Device connector configuration options
+   :header-rows: 1    
+
+   * - Field
+     - Device connector type
+     - Description
+   * - ``agent_name``
+     - all
+     - Name of the device connector (short string, no spaces)
+   * - ``device_ip``
+     - all
+     - IP address of the device used during provisioning
+   * - ``reboot_script``
+     - all 
+     - List of commands that can be executed to hard reboot the device
+   * - ``serial_host``
+     - all 
+     - (optional) ``ser2net`` host for capturing serial output
+   * - ``serial_port``
+     - all 
+     - (optional) ``ser2net`` port for capturing serial output
+   * - ``max_reserve_timeout``
+     - all 
+     - Maximum amount of time (in seconds) that a user can request to reserve a system during the reserve phase
+   * - ``env``
+     - all 
+     - mapping of key value pairs of environment data that will be injected into the runtime environment on the agent host during the test phase
+   * - ``testflinger_server``
+     - multi
+     - URL for the Testflinger server to connect to for creating subordinate test jobs used by a multi-job configuration
+   * - ``maas_user``
+     - maas
+     - MaaS profile ID configured on the agent host to use for controlling the agent
+   * - ``node_id``
+     - maas
+     - MaaS Node ID for the specific agent on the MaaS server associated with this test device
+   * - ``reset_efi``
+     - maas
+     - Attempt to reset EFI systems to boot from the network in order to work around issues with the boot order sometimes getting lost on systems that require USB Ethernet dongles
+   * - ``clear_tpm``
+     - maas
+     - Attempt to clear the TPM before provisioning the system, for SecureBoot systems
+   * - ``snappy_writable_partition``
+     - dragonboard
+     - The writable partition for injecting the cloud-init user data for enabling a default user
+   * - ``post_flash_cmds``
+     - netboot
+     - Netboot device connector specific steps needed after flashing the image that may be device-specific
+   * - ``recovery_cmds``
+     - oemrecovery
+     - List of commands to execute that will trigger “recovery” on the specified device
+   * - ``control_switch_device_cmd``
+     - muxpi
+     - Muxpi/SDWire command to execute to switch control of the SD card over to the test device so that it can boot the image
+   * - ``control_switch_local_cmd``
+     - muxpi
+     - Muxpi/SDWire command to execute to switch control of the SD card over to the SD MUX controller so that it can flash an image
+   * - ``post_provision_script``
+     - muxpi
+     - List of commands that must be executed on the test device after provisioning, with the test image mounted, for doing device-specific configuration
+   * - ``control_host``
+     - cm3, muxpi
+     - IP of the sidecar device or “controller” that can be used to assist with provisioning. This device should already be configured for ssh using a key on the agent host.
+   * - ``control_user``
+     - cm3, muxpi
+     - User to ssh to on the control_host (default: ``ubuntu``)
+   * - ``test_device``
+     - cm3, dragonboard, muxpi, netboot
+     - Block device used for writing the test image. This device will be erased and overwritten with the requested image for provisioning.
+   * - ``select_master_script``
+     - dragonboard, netboot
+     - List of commands used to force booting into the “stable” image that is used for provisioning the device
+   * - ``select_test_script``
+     - dragonboard, netboot
+     - List of commands used to force booting into the “test” image once provisioning is complete
+
+Example configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+
+  agent_name: rpi-example
+  device_ip: <DEVICE_IP>
+  control_host: <HOST_IP>
+  test_device: /dev/sda
+  serial_host: <HOST_IP>
+  serial_port: <PORT>
+  reboot_script:
+  - snmpset -c private -v2c <IP> .1.3.6.1.4.1.13742.6.4.1.2.1.2.1.8 i 0
+  - sleep 30
+  - snmpset -c private -v2c <IP> .1.3.6.1.4.1.13742.6.4.1.2.1.2.1.8 i 1
+  env:
+    DEVICE_IP: <DEVICE_IP>
+    WPA_AC_SSID: my-ac-ap
+    WPA_AC_PSK: mypassword
+    OTHER_DEVICE_DETAIL: foo

docs/reference/device-connector-types.rst

@@ -0,0 +1,32 @@
+Supported device connector types
+=================================
+
+The following device connector types are currently supported. Note that with the exception of “noprovision” and “maas2”, most of these device connectors require special hardware and/or configuration that is specific to our lab environment. However, the intent is that device connectors can be written to contain any amount of special handling necessary to handle any site-specific requirements.
+
+To specify the commands to run by the device in each test phase, set the ``testflinger-device-connector`` command in the :doc:`Testflinger agent host configuration file <testflinger-agent-conf>` for each device connector. You can optionally configure each command to be called with different parameters or using containers.
+
+.. list-table:: Supported device connector types
+   :header-rows: 1
+
+   * - Device connector type
+     - Description
+   * - cm3 
+     - Raspberry Pi Compute modules. This requires a sidecar device, along with some custom cabling and software to handle putting the cm3 into a mode where it can be provisioned, then booting it.
+   * - dragonboard 
+     - Qualcomm Dragonboard 410c setup to boot from both a special image on a USB stick when the SD card is erased, as well as an SD card that can be provisioned by booting the stable image on a USB stick and then flashing the new image to the SD card.
+   * - maas2 
+     - Uses `MaaS <https://maas.io/>`_ to provision supported images on devices that are capable of being controlled by a MaaS server.
+   * - multi 
+     - Experimental device type that is used for provisioning multiple other devices in order to coordinate a job across multiple devices at the same time.
+   * - muxpi 
+     - MuxPi or SDWire device capable of multiplexing the SD card so that it can be written, then control can be switched to the DUT to boot the image.
+   * - netboot 
+     - Special purpose device connector for a few devices that must be booted and flashed remotely but the image they need is not compatible with MaaS.
+   * - noprovision 
+     - General device connector that does not support provisioning, but can run tests on a device where provisioning is not needed or not possible to do automatically.
+   * - oemrecovery 
+     - device connector where provisioning involves triggering a “recovery” mode to reset the image back to its original state.  This is useful for things like Ubuntu Core images with full disk encryption, which can be preloaded with cloud-init data to ensure user creation, then a command is configured for the device connector that will cause it to be reset back to its original state.
+   * - dell_oemscript
+     - This device connector is used for Dell OEM devices running certain versions of OEM supported images that can use a recovery partition to recover not only the same image, but in some cases, other OEM image versions as well.
+   * - lenovo_oemscript 
+     - This device connector is used for Lenovo OEM devices running certain versions of OEM supported images that can use a recovery partition to recover not only the same image, but in some cases, other OEM image versions as well.

docs/reference/index.rst

@@ -1,4 +1,22 @@
 Reference
 =========
 
+The references in this section provide additional information about using Testflinger, supported devices, available configuration options and more.
 
+Working with device connectors
+---------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    device-connector-types
+    device-connector-conf
+
+Working with Testflinger servers and agents
+--------------------------------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    testflinger-server-conf
+    testflinger-agent-conf

docs/reference/testflinger-agent-conf.rst

@@ -0,0 +1,81 @@
+Testflinger agent configuration options
+========================================
+
+By default, configuration of Testflinger agents is loaded from a yaml configuration file called ``testflinger-agent.conf``. You can specify a different file to use for config data using the ``-c`` option.
+
+The following configuration options are supported by the Testflinger Agent:
+
+.. list-table:: Testflinger agents configuration options
+    :header-rows: 1
+
+    * - Field
+      - Description  
+    * - ``agent_id``
+      - Unique identifier for this agent
+    * - ``polling_interval``
+      - Time to sleep between polling for new tests (default: 10s)
+    * - ``server_address``
+      - Host/IP and port of the Testflinger server
+    * - ``execution_basedir``
+      - Base directory to use for running jobs (default: ``/tmp/testflinger/run``)
+    * - ``logging_basedir``
+      - Base directory to use for agent logging (default: ``/tmp/testflinger/logs``)
+    * - ``results_basedir``
+      - Base directory to use for temporary storage of test results to be transmitted to the server (default: ``/tmp/testflinger/results``)
+    * - ``logging_level``
+      - Python log level name to use for logging (default: ``INFO``)
+    * - ``logging_quiet``
+      - If enabled, logs are only written to the logfile, and not to the console (default: ``False``)
+    * - ``job_queues``
+      - List of queues that can be serviced by this device
+    * - ``advertised_queues``
+      - List of public queue names that should be reported to the server to report to users
+    * - ``advertised_images``
+      - List of images to associate with a queue name so that they can be referenced by name when using Testflinger reserve
+    * - ``global_timeout``
+      - Maximum global timeout (in seconds) a job is allowed to specify for this device connector. The job will timeout during the provision or test phase if it takes longer than the requested global_timeout to run. (Default 4 hours)
+    * - ``output_timeout``
+      - Maximum output timeout (in seconds) a job is allowed to specify for this device connector. The job will timeout if there has been no output in the test phase for longer than the requested output_timeout. (Default 15 min.)
+    * - ``setup_command``
+      - Command to run for the setup phase
+    * - ``provision_command``
+      - Command to run for the provision phase
+    * - ``firmware_update_command``
+      - Command to run for the firmware_update phase
+    * - ``allocate_command``
+      - Command to run for the allocate phase
+    * - ``test_command``
+      - Command to run for the testing phase
+    * - ``reserve_command``
+      - Command to run for the reserve phase - used for optionally reserving a system after provisioning and testing have completed.
+    * - ``cleanup_command``
+      - Command to run for the cleanup phase
+    * - ``provision_type``
+      - (Optional) type of device connector used. This is sometimes useful when templating the call to the external device-agent command, but is not required. For the list of supported provision types, see :doc:`device-connector-types`.
+
+Example configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+
+  agent_id: rpi-example
+  server_address: https://testflinger.canonical.com
+  global_timeout: 43200
+  output_timeout: 8000
+  execution_basedir: /home/ubuntu/testflinger/rpi-example/run
+  logging_basedir: /home/ubuntu/testflinger/rpi-example/logs
+  results_basedir: /home/ubuntu/testflinger/rpi-example/results
+  logging_level: WARNING
+  job_queues:
+      - rpi4
+      - rpi4-001
+  setup_command: echo Nothing needed for setup
+  provision_command: testflinger-device-connector muxpi provision -c /path/to/default.yaml testflinger.json
+  firmware_update_command: echo Updating device firmware to the latest version
+  allocate_command: testflinger-device-connector muxpi allocate -c /path/to/default.yaml testflinger.json
+  # You may want to consider running test_command under a container
+  # in order to ensure a clean environment every time
+  test_command: testflinger-device-connector muxpi test -c /path/to/default.yaml testflinger.json
+  reserve_command: testflinger-device-connector muxpi reserve -c /path/to/default.yaml testflinger.json
+  cleanup_command: echo Consider removing containers or other necessary cleanup steps here
+  provision_type: muxpi

docs/reference/testflinger-server-conf.rst

@@ -0,0 +1,40 @@
+Testflinger server configuration options
+========================================
+
+The configuration values of Testflinger servers are read from environment variables. If you prefer to store the configuration in a config file, the config file should be sourced prior to running the server so that the values may still be read from the environment.
+
+
+.. list-table:: Testflinger server configuration options
+   :header-rows: 1
+
+   * - Field
+     - Description
+   * - ``MONGODB_USERNAME``
+     - Username for connecting to MongoDB
+   * - ``MONGODB_PASSWORD``
+     - Password for connecting to MongoDB
+   * - ``MONGODB_DATABASE``
+     - Name of the MongoDB database to use
+   * - ``MONGODB_AUTH_SOURCE``
+     - Name of the database to use for authentication (Default: admin)
+   * - ``MONGODB_HOST``
+     - Host or IP of the MongoDB server
+   * - ``MONGODB_PORT``
+     - MongoDB port to connect to (Default: 27017)
+   * - ``MONGODB_URI``
+     - URI for connecting to MongoDB (used instead of the above config options). For example: ``mongodb://user:pass@host:27017/dbname``
+
+
+Example configuration
+---------------------
+
+.. code-block:: shell
+
+  # These values can be used in place of environment variables to configure
+  # Testflinger. If MONGO_URI is not specified, then it will be built using the
+  # other values specified
+  MONGODB_USERNAME="testflinger"
+  MONGODB_PASSWORD="testflinger"
+  MONGODB_DATABASE="testflinger_db"
+  MONGODB_HOST="mongo"
+  MONGODB_URI="mongodb://mongo:27017/testflinger_db"