Many miscellaneous updates made to topo docs

docs/gameboard/admin-settings.md

@@ -69,7 +69,7 @@ These settings pertain to registration, execution, and general game and challeng
 
 **Closes:** The date and the time that your game ends.
 
-**Session Duration:** The duration of game session in minutes.
+**Session Duration:** The duration of game session in minutes. Games are created with a default session time of 60 minutes.
 
 **Session Limit:** The maximum number of sessions -- a session is when a game is started and challenges can be deployed and solved -- per game.
 

docs/topomojo/admin-log.md

@@ -0,0 +1 @@
+The **Logs** 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

@@ -1 +1,17 @@
-# Admin Machines
+# 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

@@ -4,9 +4,9 @@ The **Templates** tab is where you can view all of the templates that exist in T
 
 **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](/docs/topomojo/img/templates-filter.png)
+![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. In the screen print below, 
+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"
 
@@ -26,7 +26,7 @@ TopoMojo does not append the isolation tag to persistent/shared networks listed
 
 For more information on *isolation tags*, see "Isolation tags" in [TopoMojo concepts](index.md).
 
-**Guest Settings:**
+**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.
 

docs/topomojo/admin-users.md

@@ -1,34 +1,36 @@
 # Admin Users
 
-The **Users** tab is where Topo users are created and assigned roles. 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*. 
+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:** 
+**View:** Select **View** to see the properties for the user. The properties are defined under "Create a new User" below.
 
-**Delete:**
+**Delete:** Deletes the user.
 
 ## Roles
 
-- **Admin:**
-- **Observer:**
-- **Creator:**
-- **Builder:**
-- **User:**
-- **Disabled:** 
+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:**
+**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:**
+**Workspace Limit:** The maximum number of workspaces this user can manage.
 
-**Gamespace Limit:**
+**Gamespace Limit:** The maximum number of concurrent gamespaces allowed for this user.
 
-**Gamespace Max Duration:**
+**Gamespace Max Duration:** The maximum amount of minutes allowed for a gamespace.
 
-**Gamespace Cleanup Grace time:**
+**Gamespace Cleanup Grace time:** The number of "grace" minutes between the time the gamespace expires and when it is torn down.
 
-**Generate ApiKey:**
+**Generate ApiKey:** Generate API keys here. This allows users to programmatically interact with the TopoMojo API without needing to log in.

docs/topomojo/building-a-workspace.md

@@ -1,6 +1,6 @@
 # Building a new workspace
 
-The workspace interface contains six tabs: Settings, Templates,  Document, Challenge, Files, and Play. To build a new Topo workspace click **Home**, the **New Workspace**.
+The workspace interface contains six tabs: Settings, Templates,  Document, Challenge, Files, and Play. To build a new Topo workspace click **Home**, then **New Workspace**.
 
 ## Settings
 

docs/topomojo/challenge.md

@@ -1,6 +1,6 @@
 # Challenge tab
 
-The *Challenge* tab in the Topo workspace is used when both Gameboard and TopoMojo are integrated to execute a cyber competition. More information on linking those two applications together can be found elsewhere in the Foundry documentation. The Challenge tab is where you create random key/values, embed them in a *gamespace* at deploy time, and ask questionsand answers of competitors (players).
+The *Challenge* tab in the Topo workspace is used when both Gameboard and TopoMojo are integrated to execute a cyber competition. More information on linking those two applications together can be found elsewhere in the Foundry documentation. The Challenge tab is where you create random key/values, embed them in a *gamespace* at deploy time, and ask questions and answers of competitors (players).
 
 ## Transforms
 
@@ -36,7 +36,9 @@ A *variant* describes a different version of a challenge. Variants can contain d
 
 **Question:** Enter the question you expect the participant to answer here. Your question should be specific, so that there is only one correct answer.
 
-**Answer:** Enter the correct answer that the competitor must submit to to earn a score.
+**Answer:** Enter the correct answer that the competitor must submit to earn a score.
+
+These options are revealed when **Detail** is selected.
 
 **Hidden:** Select **Hidden** to prevent the question from appearing when playing the challenge. Hidden questions do not appear when playing in TopoMojo or via Gameboard.
 

docs/topomojo/copy-paste.md

@@ -11,18 +11,15 @@ The procedures below show you how to:
 
 ## From local ("out-of-game") to in-game  
 
-1. **On your local machine:** select, then copy, the content you want to place into a launched virtual machine.
-2. **In the VM console tab:** select the cog icon (the **Tools**); under **Clipboard** paste in the clip using right-click Paste or `ctrl+V`. 
+1. On your local machine: select, then copy, the content you want to place into a launched virtual machine.
+2. In the VM console tab: select the cog icon (the **Tools**); under **Clipboard** paste in the clip using right-click Paste or `ctrl+V`. 
 3. In the VM, select where you want the copied text to go (this can be a new file or an open application, etc.).
 4. Under **Clipboard**, click **Paste**. This inserts the copied content into the virtual machine.
-
 ![console-paste](img/console-paste.png)
 
 ## From in-game to out of game
 
-1. **On the VM:** select the content you would like to copy. Copy the content *first* to the VM's clipboard (right-click Copy or `ctrl+C`).
+1. On the VM: select the content you would like to copy. Copy the content *first* to the VM's clipboard (right-click Copy or `ctrl+C`).
 2. Once you've copied your text to the VM clipboard: select the cog icon (the **Tools**), place your cursor in that clipboard and click **Copy**. This transfers the VM clip to your local clipboard.
-
-   ![console-copy](img/console-copy.png)
-
-3. **On your local machine:** paste the copied text into an application using right-click Paste or `ctrl+V`.
+![console-copy](img/console-copy.png)
+3. On your local machine: paste the copied text into an application using right-click Paste or `ctrl+V`.

docs/topomojo/files.md

@@ -1,5 +1,23 @@
-## Files
-
 The **Files** page in the Topo workspace allows you to upload files from your system to TopoMojo to include in your lab. These files are used as ISOs that can be attached to VMs in the workspace. If your files aren’t already in an ISO file format, TopoMojo wraps them in an ISO after upload.
 
-Unselecting the **Local** filter shows ISOs that are globally available in TopoMojo.
+!!! note
+
+    For ISO uploads to work, TopoMojo needs an NFS (Network File System) datastore presented to vSphere and Topo must be able to access it. 
+
+The **Files** tab in TopoMojo is where ISO files are uploaded to attach to virtual machines. Supply the ISO that you want to attach to your VM here to provide additional resources to a VM that might not be included in the original VM. ISO files are disk images that can be mounted as virtual CD drives on the VM. You want to attach an ISO when you need additional software, datasets, or other resources.
+
+**Drag and Drop:** Admins drag their ISO file into the box on Files tab or browse to locate it on their own device.
+
+By default, the **Local** filter is applied so it only displays ISOs available in the current workspace. 
+
+When you upload an ISO file in the box, TopoMojo creates a folder with *this* GUID--called out in green in screen print 1 below--in the folder name in the NFS datastore. TopoMojo puts your ISO in that folder. Only the current workspace, that is, *your* workspace has access to the ISO file. 
+
+*Screen print 1: GUID and Local filter applied*
+
+![iso-drag](img/iso-drag.png)
+
+When the **Local** filter is removed, *all* of the ISOs in the global folder on the NFS data store can be seen. (The folder name will contain a GUID of all zeros.) These global ISOs are available to every workspace in TopoMojo.
+
+ISOs can be attached to a VM in the workspace, **Templates** tab, **Settings**. See "Adding and editing templates" in the [Building a new Workspace](building-a-workspace.md) chapter of this guide. When an ISO is selected here, the ISO will be attached to the VM upon its deployment.
+
+ISOs can also be attached to VM in the workspace, **Challenge** tab, **Variant Detail**. This is called "dynamic ISO attachment" and gives you the ability to attach a variant-specific ISO file to a template. You *must* specify a target(s) here. See also "Variants" in the [Challenge tab](challenge.md) chapter of this guide.

docs/topomojo/getting-started.md

@@ -25,7 +25,7 @@ Use the `Pod__Vlan__Reservations` environment variable to define the name of a p
 - `Pod__Vlan__Reservations__0__Id:` defines the vlan Id (from the hypervisor) that corresponds to the shared/persistent network. 
 - `Pod__Vlan__Reservations__0__Name:` defines the name of the persistent/shared network. 
 
-More than one shared/persistent network can be defined by incrementing the variable name (`Pod__Vlan__Reservations__1__Id` and `Pod__Vlan__Reservations__1__Name`. To connect VMs to shared/persistent networks, users must have at least **Builder** permissions. 
+More than one shared/persistent network can be defined by incrementing the variable name (`Pod__Vlan__Reservations__1__Id` and `Pod__Vlan__Reservations__1__Name`). To connect VMs to shared/persistent networks, users must have at least **Builder** permissions. 
 
 !!! note "A note about bridge-net"
 

docs/topomojo/index.md

@@ -4,9 +4,9 @@ This documentation introduces users to the TopoMojo environment and provides inf
 
 ## 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 a highly-isolated and secure virtual-machine environment.
+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.
+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.
 
@@ -16,7 +16,7 @@ New topologies can be rapidly deployed using existing templates or built from th
 
 ### 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*. 
+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. 
 

docs/topomojo/play.md

@@ -1,8 +1,6 @@
-## Play 
+The **Play** page is where you can interact with your lab in the same way others will when they launch your content or "play" through your challenge. Play deploys a read-only copy of all virtual machines in the workspace; this gives the player their own deployed configurations.
 
-The **Play** page is where you can interact with your lab in the same way others will when they launch your content or "play" through your challenge. *Play* deploys a read-only copy of all of the virtual machines in the workspace giving the player their own set of deployed configurations.     
-
-**Variant:** Specify which variant of the challenge you wish to play (if it is a _variant_ challenge).
+**Variant:** Specify which variant of the challenge you wish to play (if it is a *variant* challenge).
 
 **Max Attempts:** The maximum number of submission attempts allowed when answering questions.
 
@@ -12,4 +10,4 @@ The **Play** page is where you can interact with your lab in the same way others
 
 **Start:** Starts up the gamespace which includes setting the timer, deploying virtual machines, displaying the Markdown document, and making challenge questions available. Individuals get their own Play tab, so when playing, the gamespace environment is unique to you.
 
-**Reset:** Resets the gamespace. <!--seems obvious enough; what other details should be added?-->
+**Reset:** Resets the gamespace.