Embedded Lab 1
==============

This is the configuration and setup information for the lab.

Settings
--------

The file `settings.conf` contains the various variables to use.

### Misc
- labuser - The user that can modify the database, and is used to login
  for generating API Keys.
- labuserzfs - The root ZFS FS for which user data will be stored.  This
  is where board clones will be made, i.e. $labuserzfs/$user/$board.  A
  proper user quota should be set on this FS.
- ifacebridge - The bridge interface to add the epair interface for network
- devfsdefaultruleset - The base devfs ruleset that all jails start with.


### Directories

- labhome - Home directory where state information about the lab is kept.
  This includes things like the database for the API, ssh keys, etc.
- labbin - Directory where the binaries and scripts live.  This is where
  the `settings.conf` file exists, and the scripts like setting up the
  jail, and deploying the ssh keys.  Simply, where this repository is
  located.
- userzfsmount - The directory that the ZFS dataset labuserzfs is mounted
  at.  When doing operations like populating jails, or creating them, this
  is the directory that should be used.


### Resource Dirs

These list the various resources used/allocated by the system.  The
directory contains directories where the name is the value of the
resource.  Directories are used because posix guarantees atomic
create/delete of directories, ensuring that an error occures if the
operation fails.

- devfsruleresourcedir - This is the set of devfs rules.
- ipresourcedir - This is the set of IP addresses available.


### Scripts

- keygencmd - Command used to generate a key for the specified user, and
  add it to the database.


### Data files

- labkeys - File that contains lines of "<user> <ssh public key>".  This
  is used by update_authkeys.sh to populate labauthfile (aka
  authorized_keys).
- db_file - SQLite3 database file that contains API keys and other
  information.

### Internal
- labuid - This is 742, and is used by the setup script.  It should not
  be modified.


Misc Files
----------

`base_setup.sh`: Script to setup a base image w/ various defaults

`board_conf.ucl`: UCL configuration file for the embedded lab daemon

`board_script`: Script that is run by the daemon, that reserves and
releases the specific board.  It allocates resources (such as local
IP address) and launches the jail, and when the board is released,
it frees up the various resources.

`create_resource`: Script used by `setup_resources.sh` to initalize
the various resources when this is first configured.

`keygen`: Script for generating a new API key for the specified user.
This is used by the `update_authkeys.sh` script.

`rc.conf.template`: Template `rc.conf` for jails.

`setup_lab.sh`: Script to setup the machine for the first time to run
the lab.

`setup_resources.sh`: Script to setup initial resources.

`test.*`: File and script to test that `board_script` does what is
expected.

`update_authkeys.sh`: A script used to generate the `authorized_keys`
file.  The input is a file with each line containing the user followed
by their ssh-key.  It will restrict that key to run the `keygen` script
to get the user an API key.


SNMP
----

SNMP is used to control a PoE switch which provides power to various
boards.  NetSNMP is used.  It requires a little bit of setup.  First is
to set the default version to 3.  Despite v1 being more common, v3
provides better security.

### Configure NetSNMP

`~root/.snmp/snmp.conf`:
```
defVersion 3
```

NetSNMP will use a file `.snmp/hosts/<hostname>.conf` to set various
parameters.  For example:
```
defVersion 3
defSecurityName admin
defAuthPassphrase XXXYYYZZZ
defAuthType SHA
defPrivPassphrase WWWUUUVVV
defPrivType DES
defSecurityLevel authPriv

transport <ip address>
```

This segments where authentication credentials are stored, and allows
using names w/o having to enter them into a DNS server.


### Configure switch

The program [vlanmang](https://www.funkthat.com/gitea/jmg/vlanmang) is
used to maintain the configuration of the switch, most specifically
what ports are connected to which VLAN.

The file `data.py` contains the configuration information.  It will
read the auth methods and passwords from the NetSNMP configuration
files setup in the previous section.

Setup `vlanmang`:
```
ln -s ~lab/.local ~root
python3.8 -m venv venv
. ./venv/bin/activate
export TMPDIR=/var/tmp
pip install git+https://www.funkthat.com/gitea/jmg/vlanmang.git
```

Configure switches:
```
. ./venv/bin/activate
python -m vlanmang
```