Confidential Data Workspace Initial Docs

docs/access/index.md

@@ -18,10 +18,16 @@ how to apply for a new project
 [VDI access to virtual machines](./virtualmachines-vdi.md): how to connect to the virtual
 desktop interface.
 
+[VDI access to Confidential Data Workspace VMs](../services/confidentialdataworkspace/quickstart.md): how to connect to the Confidential Data Workspace service.
+
 ## SSH Access to Virtual Machines
 
 Users with the appropriate permissions can also [use `ssh` to login to Virtual Desktop VMs](./ssh.md)
 
+## SSH Access to Confidential Data Workspace Service
+
+Remote SSH access to Confidential Data Workspace VMs is **disabled** for security of the service, access is provided through the Guacamole web interface only. Access is described in the [Confidential Data Workspace Quickstart](../services/confidentialdataworkspace/quickstart.md) guide.
+
 ## SSH Access to Computing Services
 
 Includes access to the following services:

docs/access/virtualmachines-vdi.md

@@ -14,7 +14,7 @@ Authentication to the VDI is provided by SAFE, so if you do not have an active w
 you will be redirected to the [SAFE log on page](https://safe.epcc.ed.ac.uk).
 If you do not have a SAFE account follow the instructions in the
 [SAFE documentation](https://epcced.github.io/safe-docs/safe-for-users/)
-how to register and receive your password.
+on how to register and receive your password.
 
 ## Navigating the EIDF VDI
 

docs/services/confidentialdataworkspace/docs.md

@@ -0,0 +1,216 @@
+# Service Documentation
+
+## Project Management Guide
+
+### User Roles and Their Permissions
+
+!!! info
+    All names are separate from those in SAFE and are for the purpose of the EIDF Confidential Data Workspace service only
+
+**Data Users** - _Typical users - have access to read only on some data directories_
+
+**Data managers** - _Have read and write access to some data directories_
+
+**VM Admin** - _Access to the data manager group (project wide) and sudo access (per VM)_
+
+#### Detailed Roles, Groups and Their File Permissions
+
+A description of the roles defined within the EIDF Confidential Data Workspace service and some access they have is given in the below table.
+For those familiar with Trusted Research Environments (TREs) the following table includes a mapping of roles in the EIDF Confidential Data Workspace service which are conceptually similar to the roles in a TRE.
+
+| Role         | TRE Equivalent User  | Router Access | Should be given sudo permissions on VMs & router |
+| ------------ | -------------------- | ------------- | ------------------------------------------------ |
+| Data User    | Researcher           | No            | No                                               |
+| Data Manager | Research Coordinator | No            | No                                               |
+| VM Admin     | N/A                  | Yes           | Yes                                              |
+
+There are a few different roles associated with Confidential Data Workspace projects that determine what actions a user can perform in the EIDF Portal.
+
+| Group                           | Files                                       | Permission | Note                                                                                                                                                     |
+| ------------------------------- | ------------------------------------------- | ---------- | ----------------------------------------------------------------------                                                                                   |
+| `sudo` group on router machine  | `/etc/squid/allowlist_buckets.txt`          | Owner W+R  | (implicit via machine access)                                                                                                                            |
+|                                 | `/etc/squid/allowlist_domains.txt`          | Owner W+R  | (implicit via machine access)                                                                                                                            |
+|                                 | `/etc/squid/squid.conf`                     | Owner W+R  | (implicit via machine access; Squid proxy configuration)                                                                                                 |
+| `sudo` group on a CDW VM        | Permissions of `<project-name>-datamanager` | Owner W+R  |                                                                                                                                                          |
+| `<project-name>-datamanager`    | `/data/datamanager`                         | W+R        | Project shared area for data managers to stage and manage data for import into and export from Confidential Data Workspace VMs via approved transfer methods. |
+
+### Updating the Allowed Access Configuration for Confidential Data Workspace VMs
+
+See [router-docs.md](router-docs.md) for documentation on updating the allowed access configuration for Confidential Data Workspace VMs.
+
+### Create a VM
+
+To create a new Confidential Data Workspace VM:
+
+1. Select the project from the list of your projects, e.g. `eidfxxx`
+1. Click on the 'New Private Machine' button
+1. Complete the 'Create Machine' form as follows:
+
+    1. Select the 'Confidential Data Workspace' router to use, typically this will be the default router for your project e.g. `eidfxxx-router`
+    1. Provide an appropriate name, e.g. `dev-01`. The project code will be prepended automatically to your VM name, in this case your VM would be named `eidfxxx-dev-01`.
+    1. Select a suitable operating system
+    1. Select a machine specification that is suitable
+    1. Choose the required disk size (in GB) or leave blank for the default
+    1. Tick the checkbox "Configure RDP access" if you would like to install RDP
+      and configure VDI connections via RDP for your VM.
+
+1. Click on 'Create'
+1. You should see the new VM listed under the 'Machines' table on the project page and the status as 'Creating'
+1. Wait while the job to launch the VM completes.
+   This may take up to 10 minutes, depending on the configuration you requested.
+   You have to reload the page to see updates.
+1. Once the job has completed successfully the status shows as 'Active' in the list of machines.
+
+You may wish to ensure that the machine size selected (number of CPUs and RAM) does not
+exceed your remaining quota before you press Create, otherwise the request will fail.
+
+In the list of 'Machines' in the project page in the portal,
+click on the name of new VM to see the configuration and properties,
+including the machine specification, its `10.24.*.*` IP address and any configured VDI connections.
+
+### Quota and Usage
+
+Quotas and Usage are the same as those for the [standard EIDF VM service](../virtualmachines/docs.md#quota-and-usage).
+
+Each project has a quota for the number of instances, total number of vCPUs, total RAM and storage.
+You will not be able to create a VM if it exceeds the quota.
+
+You can view and refresh the project usage compared to the quota in a table near the bottom of the project page.
+This table will be updated automatically when VMs are created or removed, and
+you can refresh it manually by pressing the "Refresh" button at the top of the table.
+
+Please contact the helpdesk if your quota requirements have changed.
+
+### Add a User Account
+
+User accounts allow project members to log in to the VMs in a project.
+The Project PI and project managers manage user accounts for each member of the project.
+Users usually use one account (username and password) to log in to all the VMs in the same project that they can access,
+however a user may have multiple accounts in a project, for example for different roles.
+
+1. From the project page in the portal click on the 'Create account' button under the 'Project Accounts' table at the bottom
+1. Complete the 'Create User Account' form as follows:
+
+    1. Choose 'Account user name': this could be something sensible like the first and last names
+    concatenated (or initials) together with the project name.
+    The username is unique across all EPCC systems so the user will not be able to reuse this name
+    in another project once it has been assigned.
+    1. Select the project member from the 'Account owner' drop-down field
+    1. Click 'Create'
+
+The user can now set the password for their new account on the account details page.
+
+### Setting Up the Correct Groups and Permissions for User Accounts
+
+Portal management of VMs and user accounts can only be done by project members with **Cloud Admin** permissions. This includes the principal investigator (PI) of the project and all project managers (PM). The PI and PMs can grant a project member the **Cloud Admin** role through the SAFE. There is more information in the virtual machine documentation under the section [Required Member Permissions](../virtualmachines/docs.md#required-member-permissions).
+
+User accounts should be placed in the correct groups on the VM to ensure they have the correct file permissions and data access. When a user account is created in the portal it will be added to the default group `<project-name>`. If the user account requires Data Manager access they must be added to the `<project-name>-datamanager` group. The VM Admin must be added to this group also.
+
+The VM Admin must be given sudo permissions on each VM to have the necessary permissions for managing restricted VMs and router configuration. Unlike addition to the `datamanager` group, sudo permissions are set on a per-VM basis via the portal.
+
+The following sections give instructions for setting up the required groups for the different roles in a Confidential Data Workspace project:
+
+- For creating and adding users to the `datamanager` group under the SAFE see [Creating a group](https://epcced.github.io/safe-docs/safe-for-managers/#how-can-i-set-up-project-groups-within-my-project) and then [adding users to the group](https://epcced.github.io/safe-docs/safe-for-managers/#how-can-i-add-users-to-an-existing-project-group)
+- See the Virtual Desktop Interface documentation for [Sudo Permissions](../virtualmachines/docs.md#sudo-permissions) for guidance on giving sudo permissions to the VM Admin role for each VM.
+
+## Adding Access to the VM for a User
+
+User accounts can be granted or denied access to existing VMs.
+
+1. Click 'Manage' next to an existing user account in the 'Project Accounts' table on the project page, or click on the account name and then 'Manage' on the account details page
+1. Select the checkboxes in the column "Access" for the VMs to which this account should have access or uncheck the ones without access
+1. Click the 'Update' button
+1. After a few minutes, the job to give them access to the selected VMs will complete and the account status will show as "Active".
+
+If a user is logged in already to the VDI at [https://eidf-vdi.epcc.ed.ac.uk/vdi](https://eidf-vdi.epcc.ed.ac.uk/vdi)
+newly added connections may not appear in their connections list immediately.
+They must log out and log in again to refresh the connection information, or wait until the login token expires and is refreshed automatically - this might take a while.
+
+If a user only has one connection available in the VDI they will be automatically directed to the VM with the default connection.
+
+### Sudo Permissions
+
+Sudo permissions should only be granted to users in the VM Admin role to restrict as much as possible the data management capabilities of users in the Confidential Data Workspace environment and remove the opportunity for data ingress/egress outwith the proper channels.
+
+## First Login
+
+A new user account must reset the password before they can log in for the first time.
+To do this:
+
+1. The user can log into the [Portal](https://portal.eidf.ac.uk) and select their project from the 'Projects' drop-down.
+1. From the project page, they can select their account from the 'Your Accounts' table
+1. Finally, click the 'Set Password' button from the 'User Account Info' table.
+
+Users will then be able to log in using the VDI as described in the [VDI documentation](../../access/virtualmachines-vdi.md).
+
+!!! Warning
+    Access to the Confidential Data Workspace VMs is only possible through the VDI or the project router.
+    You cannot directly SSH onto the VMs, and you cannot access the VMs through the router until you have access to the router itself. Please see the documentation section on [SSH Access to the Confidential Data Workspace Router](./router-docs.md#ssh-access-to-the-confidential-data-workspace-router) for more information on how to access the router and then the VMs via SSH.
+
+## Updating an Existing Machine
+
+### Adding RDP Access
+
+The instructions in this section match the instructions given in the [EIDF Virtual Machine Service Documentation](../virtualmachines/docs.md#adding-rdp-access).
+
+If you did not select RDP access when you created the VM you can add it later:
+
+1. Open the VM details page by selecting the name on the project page
+1. Click on 'Configure RDP'
+1. The configuration job runs for a few minutes.
+
+Once the RDP job is completed, all users that are allowed to access the VM
+will also be permitted to use the RDP connection.
+
+### Software Catalogue
+
+The instructions in this section match the instructions given in the [EIDF Virtual Machine Service Documentation](../virtualmachines/docs.md#software-catalogue).
+
+You can install packages from the software catalogue at a later time,
+even if you didn't select a package when first creating the machine.
+
+1. Open the VM details page by selecting the name on the project page
+1. Click on 'Software Catalogue'
+1. Select the configuration you wish to install and press 'Submit'
+1. The configuration job runs for a few minutes.
+
+### Patching and Updating
+
+It is the responsibility of project PIs to keep the VMs in their projects up to date as stated in the [policy](policies.md#patching-of-user-vms).
+
+!!! important "Snap packages"
+
+    Snap packages are not supported by default on the Confidential Data Workspace VMs. Snap requires data egress to install software packages. Allowing this could potentially be used to bypass the security of the Confidential Data Workspace. If you require snap packages then the VM Admin can enable usage by following the instructions in the [FAQs](./faq.md#unable-to-download-packages-from-snap-on-the-confidential-data-workspace-vms).
+
+Since updates and patches require access to the internet, users should ensure that their Confidential Data Workspace VMs have access to the sources that the operating system gets updates from. This will usually be done out of the box, but repository sources can change and may need to be updated in the squid proxy configuration. Updating of allowed sources is detailed in the documentation section [Updating the allowed access for Confidential Data Workspace VMs](router-docs.md#updating-the-allowed-access-for-confidential-data-workspace-vms).
+
+#### Ubuntu
+
+To patch and update packages on Ubuntu run the following commands (requires sudo permissions):
+
+```bash
+sudo apt update
+sudo apt upgrade
+```
+
+Your system might require a restart after installing updates.
+
+#### Rocky
+
+To patch and update packages on Rocky run the following command (requires sudo permissions):
+
+```bash
+sudo dnf update
+```
+
+Your system might require a restart after installing updates.
+
+### Reboot
+
+When logged in you can reboot a VM with this command (requires sudo permissions):
+
+```bash
+sudo reboot now
+```
+
+or use the reboot button in the EIDF Portal (requires project manager permissions).