integration of topomojo documentation

docs/topomojo/about.md

@@ -0,0 +1,50 @@
+# TopoMojo Docs
+
+This documentation introduces users to the TopoMojo environment and provides information necessary to launch existing labs and create new topologies.
+
+## About TopoMojo
+
+TopoMojo--*Topo* for short--is a web application used for creating and delivering cybersecurity training labs and exercises. With TopoMojo, users can build and deploy labs in an isolated and secure virtual-machine environment.
+
+TopoMojo allows for the same functionality and connectivity that users would experience with real, physical devices. Network topologies can utilize not only IP and Ethernet, but also custom protocol solutions like 802.11 wireless packet simulation.
+
+New topologies can be rapidly deployed using existing templates or built from the ground up with user-provided ISO's and VM specifications.
+
+**Go to the TopoMojo repository:** [github.com/cmu-sei/TopoMojo](https://github.com/cmu-sei/TopoMojo).
+
+## TopoMojo concepts
+
+### Workspace and Gamespace
+
+You build your content in a *workspace*, but you "play" (complete the lab, do the activity) in a *gamespace*. The workspace is where a virtual topology is built. Here engineers and lab developers add VMs, save updates, author a guide in Markdown, and configure questions/answers to turn the topology into a lab or *challenge*.
+
+A *gamespace* is where someone else plays through the lab. They get their own, isolated, read-only copies of all workspace resources. Players in a gamespace can interact with VMs and answer questions to complete a lab, but they can't save anything in the environment. 
+
+In short: a *gamespace* is a read-only copy of a *workspace* where a player (user) interacts with the lab content.
+
+### Isolation Tag
+
+A unique identifier TopoMojo uses to identify a workspace or gamespace. 
+
+- For a workspace: the *isolation tag* is the workspace id visible above the Workspace Title when viewing the workspace. See screen print 1.
+- For a gamespace: the *isolation tag* is the gamespace id partially visible from the **Admin**, **Gamespaces** view (see screen print 2) and fully visible in the URL bar when viewing a VM console that belongs to a gamespace (highlighted in screen print 3).  
+
+The id's used for isolation tags uniquely identify each workspace and gamespace in the TopoMojo database. Additionally, each resource (e.g., virtual machine, virtual network, etc.) associated with a workspace or gamespace will have the isolation tag appended to the resource name.  
+
+For example: a VM named `challenge-sever` in the gamespace with id (isolation tag) `18048abc66f142e1804732082f4051d2`, has the name `challenge-server#18048abc66f142e1804732082f4051d2`. Appending the isolation tag to workspace/gamespace resources ensures environment isolation -- VMs and networks cannot have the same name, so there will never be accidental sharing of VM/network resources.
+
+*Screen print 1:*
+
+![workspace iso tag](img/iso-tag-ws.png)
+
+*Screen print 2:*
+
+![gamespace iso tag](img/iso-tag-gs.png)
+
+*Screen print 3:*
+
+![iso tag url](img/iso-tag-url.png)
+
+### Challenge
+
+The term *challenge* refers to when both Gameboard and TopoMojo are integrated to execute a cyber competition. In this scenario, Gameboard is a consumer of content made in TopoMojo. More information on that is available elsewhere in the Foundry documentation.

docs/topomojo/admin-dashboard.md

@@ -0,0 +1,21 @@
+# Admin features
+
+TopoMojo has an admin interface called **Admin Dashboard**. To access the Admin Dashboard, you'll need the `admin` role. In the top-right corner, click the **Admin** button. The initial `admin` role is given to the first user who authenticates successfully.
+
+### Hub Connections
+
+**Hub connections** informs Topo admins about which users are currently logged into TopoMojo.
+
+### Announcement
+
+The **Announcement** feature allows Topo admins to broadcast important messages to everyone in TopoMojo. Announcements appear in the Topo interface. In the Message field, enter the content of the announcement and click **Send**.
+
+### Import/Export
+
+This is future functionality for the TopoMojo UI. The API equivalent of import/export is available for use.
+
+### Janitor
+
+The **Janitor** service cleans up unused resources (e.g., a workspace VM that has been idle for a long time) in TopoMojo.
+
+**Cleanup Report:** Provides a log of the Janitor's activity.

docs/topomojo/admin-gamespaces.md

@@ -0,0 +1,27 @@
+# Admin Gamespaces
+
+The **Gamespaces** tab is where the admin can search for, and filter by, **active** and **inactive** gamespaces. Once gamespaces are found, the admin can perform certain actions. By default, the search is for *active* gamespaces. Green indicates *active* gamespaces and gray indicates *inactive* gamespaces.
+
+**Refresh:** Refreshes your search.
+
+**Delete Selected:** Check the box next to **All** to select all gamespaces for deletion or check a box next to individual gamespaces to select for deletion.
+
+Gamespaces in the table show the gamespace id or support code in Gameboard (e.g. `e9416013`), the time remaining (if active), the user who is interacting with (or *had* interacted with) the gamespace; and the title of the *workspace* that the *gamespace* was deployed from. The screen print below, several active and inactive gamespaces are shown. User names have been redacted.
+
+![admin gamespaces](img/admin-gamespaces.png)
+
+## View (expanded)
+
+**View:** Selecting **View** expands the gamespace information where a list of all the VMs associated with the gamespace and their state. Additional information on how the View works is found below.
+
+- **refresh:** Refreshes the VM instance.
+- **console:** Allows you to interact with the VM (a user's gamespace).
+- **stop:** Stops a powered on VM.
+- **revert:** Reverts to last saved state.
+- **delete:** Deletes a running VM instance.
+- **Json:** Shows detailed information about the gamespace, including: answers to questions, variables associated with the challenge, submitted answers, challenge questions and expected answers, and if questions were answered correctly or incorrectly.
+- **Dispatcher:** Used to issue commands to a VM from TopoMojo provided that the TopoMojo agent program is running on that VM. The VM requires an internet connection which allows the agent program to establish a connection with TopoMojo. `target` is the hostname of the VM that you want to run the command on. `command` is any command you wish to run. See TopoMojo's [GitHub repository](https://github.com/cmu-sei/TopoMojo/tree/main/src/TopoMojo.Agent) for more information on TopoMojo's agent.
+
+## Delete
+
+**Delete:** As you would expect, deletes the gamespace and associated VMs.

docs/topomojo/admin-log.md

@@ -0,0 +1,3 @@
+# Admin Dashboard Log tab 
+
+The **Log** tab is useful from the admin point of view when trying to troubleshoot. Only errors are shown here, not every log line.

docs/topomojo/admin-machines.md

@@ -0,0 +1,17 @@
+# Admin Machines
+
+This tab provides a list of all VMs TopoMojo is tracking and the gamespaces they are attached to without the use of the vSphere Client.
+
+![admin machine explanation](img/admin-machine.png)
+
+- `gamespace` tells you this is a *gamespace* VM.
+- `pc5-ubuntu-server-2204-594` is the name of the VM.
+- `#d9b090c92728424781537c66b3ee2f4b` after the hash tag is the gamespace GUID.
+
+The **Machines** tab is helpful when you want to find all the VMs related to a gamespace (e.g., `PC6 Stock Topology v1` in the screen print above). You can copy the gamespace GUID and paste it into the **Search** field. Note that you cannot interact with the VMs from this tab.
+
+## "Orphaned" VMs
+
+VMs tagged with `__orphaned` are VMs that still exist; however, they are not connected to anything. They could have been attached to a gamespace that has since expired, and when TopoMojo asked vSphere to remove these VMs, an issue prevented vSphere from responding. Orphaned VMs should be manually deleted in vSphere.
+
+To identify orphaned VMs, search for "orphaned" in the Search field, identify the VMs to clean up in vSphere, and delete them. Once deleted in vSphere, they won't appear on the **Machines** tab again.

docs/topomojo/admin-templates.md

@@ -0,0 +1,37 @@
+# Admin Templates
+
+The **Templates** tab is where you can view all of the templates that exist in TopoMojo.
+
+**Search:** Search for templates by workspace. Notice that you can apply filters here to further narrow down your search. In the screen print below, the filter is for linked VMs with a parent template of a VM called `kali-201901`.
+
+![templates filter](img/templates-filter.png)
+
+You can filter for specific workspaces here too. Clicking the *name* of the of the workspace takes you directly to the workspace.
+
+!!! note "Linked and unlinked templates"
+
+    The chain link icon next to a template name indicates the VM is *linked*. Use linked VMs when the prebuilt, stock templates included with TopoMojo meet your needs. Linked VMs save resources when VMs don't require custom configurations when deployed. Changes can't be saved to linked VMs when deployed. Changes can only be saved to *unlinked* VMs. 
+
+## Template Properties
+
+**Name:** The VM name can't contain spaces; Topo will replace spaces in a name with a `-`.
+
+**Description:** Not visible to users; use the *Description* in a way that meets your needs. For example, VM credentials could be included here.
+
+**Networks:** A space delimited list of network names. When the VM is deployed, it will have *one* network interface for each of the named networks. Networks are created on the hypervisor by TopoMojo at VM-deploy time if they don't already exist. 
+
+TopoMojo appends the isolation tag of the workspace/gamespace to network names to ensure network isolation. 
+
+TopoMojo does not append the isolation tag to persistent/shared networks listed here; the VM will be connected to the existing shared/persistent network.
+
+For more information on *isolation tags*, see "Isolation tags" in [TopoMojo concepts](index.md).
+
+**Guest Settings:** List key value pairs in the form of `key=value` to pass data into deployed VMs via VMware guestinfo Variables. The **Guest Settings** field uses VMware Guest Info Variables to inject content into virtual machines. Key/value pairs are placed here. The *key* is the name of the guest variable you want to define, and the *value* is value, information, setting, of the variable.  For example, `var1=test` is a guest setting named “var1” with a value of “test”.
+
+**Replicas:** *Replicas* indicates how many copies of the VM get deployed in a gamespace. This will vary according to your needs. You may need two copies of the VM per gamespace or you may need 10. E.g.: two users are working a Topo lab together; we want to set Replicas to `2` to ensure that each user has their own VM to work with. If set to `1`, then the two users could encroach on each other's work on the single VM.
+
+When deciding how many replicas are needed, keep resources in mind. If, as in our example above, we only need two copies of the VM at any given time don't set Replicas to `5`. Topo will deploy five, two will get used, and the three extra won't get used everytime the gamespace is deployed.
+
+`-1`: Setting Replicas to `-1` means Topo will deploy one VM template copy per user. If there are two users, then two copies are deployed; if there are 10 users, then 10 copies. No extra VMs are deployed. This setting is used in conjunction with the Gameboard app, where Gameboard informs TopoMojo on how many copies to make based upon the Gameboard team size.
+
+The value set in **Replicas** only applies to the template you are editing; not every template in the workspace. So, if you want the same number of copies deployed in a gamespace for each template, you'll have to edit each template individually.

docs/topomojo/admin-users.md

@@ -0,0 +1,36 @@
+# Admin Users
+
+The **Users** tab is where Topo users are listed, created, and assigned permissions. The **Search** feature allows Topo admins to search on the name of a Topo user. To search for a user across all of TopoMojo, enter the term into the **Search** field or filter by *role* or *audience*. 
+
+Recall from workspace Settings that "audience" is a list of clients who can launch the workspace as a gamespace. Selecting an audience filter results in users who are part of that audience.
+
+**View:** Select **View** to see the properties for the user. The properties are defined under "Create a new User" below.
+
+**Delete:** Deletes the user.
+
+## Roles
+
+All permissions are *additive*; meaning a Creator can do everything a Builder can do and an Observer can do everything a Builder and Creator can do. 
+
+- **Admin:** Highest level of permission in TopoMojo; can do everything the other roles can do.
+- **Observer:** Allows a user to view and use the Gamespaces tab. Access is limited by the *scope* of the user (see below). An observer can deploy gamespaces with a matching *audience* and these are the only gamespaces the user can observe.
+- **Creator:** Can have as many workspaces and templates as wanted.
+- **Builder:** Can connect to bridge-net.
+- **User:** No extra permissions in TopoMojo. This is the TopoMojo default.
+- **Disabled:** No permissions in TopoMojo.
+
+## Create a new User
+
+**Name:** Enter a new user name here.
+
+**Scope:** A space-delimited list of administrator-defined groups the user belongs to. Administrators can define a *scope* with any name here. A user's scope determines which workspaces they have permission to deploy gamespaces from. Users can only deploy a gamespace from a workspace if the user has a *scope* that matches an *audience* defined in the workspace. See also: [Building a new workspace](building-a-workspace.md).
+
+**Workspace Limit:** The maximum number of workspaces this user can manage.
+
+**Gamespace Limit:** The maximum number of concurrent gamespaces allowed for this user.
+
+**Gamespace Max Duration:** The maximum amount of minutes allowed for a gamespace.
+
+**Gamespace Cleanup Grace time:** The number of "grace" minutes between the time the gamespace expires and when it is torn down.
+
+**Generate ApiKey:** Generate API keys here. This allows users to programmatically interact with the TopoMojo API without needing to log in.

docs/topomojo/admin-workspaces.md

@@ -0,0 +1,33 @@
+# Admin Workspaces
+
+The **Workspaces** tab is where the admin can search for workspaces and perform limited actions. Workspaces are where challenges (or labs) are built. Here, an admin can view every workspace.
+
+!!! note
+
+    Only users who are admins can view the list of workspaces on the Admin panel. Non-admin users will use the search feature on the left navigation pane.
+
+In the left navigation pane, you can use the **Search** field to locate a workspace. However, searching here only returns workspaces you have created or have been invited to join.
+
+**Create:** Create a new workspace from the Admin Workspaces panel.For additional help, see [Building a new workspace](building-a-workspace.md).
+
+Selecting a workspace takes you the **Settings** tab of that particular workspace where you can edit it. For additional help on the **Settings** tab, see [Building a new workspace](building-a-workspace.md).
+
+The *workspace identifier* is present here too. The workspace identifier matches the directory name used to store workspace files like unlinked virtual machines, Markdown documents, images, etc. Copying it to the clipboard is useful if you need to use it in a terminal when navigating the filesystem. The workspace identifier is called out in the screen capture below.
+
+![tm-wksp-iden](img/wksp-iden.png)
+
+## View (expanded)
+
+**Template Limit:** Defines the number of VMs that can be in the workspace.
+
+**Template Scope:** Limits a workspace to using templates that have the given scope.
+
+**Audience:** Limits who can deploy a gamespace as a workspace.
+
+**VMs:** Refresh, deploy, view the console, start/stop, revert and delete from here.
+- **Refresh**: Queries the state of the VM from the hypervisor.
+- **Deploy**: Deploys that virtual machine into your workspace.
+- **Console:** Opens the console for the virtual machine.
+- **Stop/Start:** Power off/on the VM, but leaves the resource deployed on the hypervisor. Clicking **stop** results in the hypervisor showing a deployed VM in a powered-off state.  Clicking **start** powers on the deployed VM.
+- **Revert:** Reverts the VM to its last saved state. All changes made since the last commit are lost.
+- **Delete:** Deletes a running VM instance.