VM Configurations
A VM configuration is a saved, named specification for a virtual machine: a hardware setup, an owning team, an optional project tag, a list of co-owners, a home drive, and any extra drives. A configuration is not a machine. It is the blueprint the platform assembles a machine from. Starting a configuration spawns a running VM, a live instance with its own RDP session and its own VM Controller. You can create a configuration and never start it, start it and shut it down every evening, or start it again next month. The configuration is unchanged by any of that.
Why configurations are separate from running VMs
The running VM is deliberately disposable; the configuration is what persists. A tiCrypt VM boots from a clean image that resets on every restart, so nothing installed or changed in the guest operating system survives a shutdown. Only two things carry state across restarts: your encrypted drives, which hold the data, and the VM configuration, which holds the assembly. If the configuration were fused into the running instance, shutting a VM down would destroy the record of how it was built. Separating them is what makes "shut the VM down at night, get the same machine back tomorrow" a safe default rather than a rebuild.
The configuration is where access is declared before the machine exists. Co-owners listed in the configuration are added to the running VM with the Co-owner role automatically when it starts, and the home drive, which is the first attached drive, carries the VM's user database, so accounts, roles, and permissions travel with it. Whoever actually starts the VM becomes its Owner for that session. Access to a VM is granted by its Owner and is never inherited from a system-wide admin role, so it has to be written down somewhere the platform can read before the first boot. See VM Roles and Permissions.
A project tag is a compliance decision, not a label. The project tag is applied when the machine's encrypted drives are mounted at boot. That is why changing the project of a running VM has no effect until it is restarted, and why changes you save to a configuration while its VM is starting or running take effect only at the next start. tiCrypt is enforcing the rule that a machine's regulatory classification is fixed for the life of a session: you cannot reclassify a live machine out from under the data already open on it.
Configurations are free; instances are not. A stopped configuration consumes no CPU or memory from your team's allocation, only the storage of its drives. Keeping several configurations around costs you nothing.
When to create more than one configuration
- Different operating systems: drive format determines which VMs a drive can attach to (NTFS for Windows, EXT4 or BTRFS for Linux), so a Windows analysis machine and a Linux pipeline machine must be separate configurations. Each hardware setup lists the drive formats it accepts, and the home drive of a Linux VM can never be NTFS.
- Different resource sizes: keep a small configuration for interactive editing and a large one for a memory-heavy run, both pointed at the same home drive, and start only the one you need.
- Different projects: a machine that touches regulated data under one project and a machine for unrestricted work should be separate configurations with separate tags and separate drives, so classification is never ambiguous in the audit trail.
- Different collaborators: co-owners gain access to the VM's drives. If two colleagues need different subsets of your data, give them separate configurations rather than adding everyone to one.
- Debug versus production: a hardware setup in debug mode lets admins reach into the VM to diagnose the controller. Keep debug work in its own configuration and never point production work at it.
Before you begin
- You have the Create and edit VM configurations permission. If you do not, ask your admin.
- You are a member of an active team.
- Your admin has published at least one hardware setup you can use.
- You know which drive will be the home drive, or you are ready to create one.
Create a New Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- Click New VM in the top left panel.
- In the Create new VM configuration pop-up, under Basic Information, enter a Name and select a Team. Optionally, select a Project (optional), add VM Co-owners (optional), and enter a Description (optional).
- Under Hardware Setup, select the VM hardware setup to allocate resources.
- Under Home drive, select an existing drive or click the Create new drive button to create a new drive to store the virtual machine data.
- Optionally, under Extra drives (optional), click Add a new drive for each additional drive and choose its Order, Drive, and Type, or click Create a new drive.
- Under Actions, leave the box Launch a VM from this configuration immediately ticked (the default) to start the VM right away, or untick it to only save the configuration.
- Click Create.
- If the Share drives with the co-owners of
vm-name? dialog appears, review the drives listed for each co-owner and click Share and save. For more information, see Share drive keys with co-owners.
The configuration appears in the VMs list and tiCrypt shows "Created
vm-name". If you ticked Launch a VM from this configuration
immediately, tiCrypt spawns an instance, you become its Owner, and the co-owners you listed
are added automatically with the Co-owner role. When drive keys are shared with co-owners, the VM
starts only after the sharing task finishes.
- Information about RAM disk size and mounting slot location is displayed under the Extra drives (optional) section upon VM creation.
Configuration form fields
The configuration form is the same for creating and editing. Its title is Create new VM
configuration when you create one and Update vm-name when you edit one. The later steps
unlock as you fill in the earlier ones, and the Create or Save button stays disabled
while any field is invalid.
The following table describes the fields of the Basic Information step.
| Field | Required | Description |
|---|---|---|
| Name | Yes | Up to 80 characters. The name must differ from every other configuration you can see. |
| Team | Yes | The team that owns the configuration. Only teams you belong to are offered. |
| Project (optional) | No | The project tag. Users you authorize on the VM must also be active members of this project to use it. Changing the project clears the home drive if the drive's project differs. |
| VM Co-owners (optional) | No | Other users who co-own the configuration. You are always its owner, so you are not offered. |
| Description (optional) | No | Up to 250 characters. Markdown is supported. |
| MAC Address | No | Under VM Host & MAC Address (Optional). A fixed MAC address in the form XX:XX:XX:XX:XX:XX, where each X is a hexadecimal digit. By default, a MAC address is assigned automatically. |
| Preferred host to start VM on | No | Under VM Host & MAC Address (Optional), shown only when hosts are available for the hardware setup's realm. Any host (scheduled), the default, lets tiCrypt schedule the VM to a suitable host according to its hardware requirements. |
A name may not contain any of the characters / \ | " : * ? < > { } or NUL. A description may not
contain < > { }.
The following table describes the remaining steps of the form.
| Step | Field | Description |
|---|---|---|
| Hardware Setup | Hardware Setup | Determines what software gets loaded and what hardware resources the VM has access to. Each option shows its cores, memory, and devices. A red icon marks a setup in debug mode. |
| Home drive | Home drive | The first drive of the VM, which holds the VM's user database and home directories. |
| Extra drives (optional) | Order | The slot the drive is mounted in: Auto, or a slot from E:/2 to Y:/22. Each slot can be used once. |
| Extra drives (optional) | Drive | The drive to attach. Each drive can be used once. |
| Extra drives (optional) | Type | Read-write (the default) or Readonly. A read-write drive must be writable by you and carry exactly the configuration's project. |
| Actions | Launch a VM from this configuration immediately | Starts the VM once the configuration is saved. Ticked by default when you create a configuration, unticked when you edit one. |
A drive is offered as the home drive only when all of the following are true:
- Access: you own the drive or it is shared with you, and you can write to it.
- Realm: the drive is in the same realm as the hardware setup.
- Project: the drive's project is exactly the configuration's project. A configuration without a project needs a drive without a project.
- Format: the hardware setup accepts the drive's format. A Linux hardware setup never accepts an NTFS home drive.
Extra drives follow the same realm and format rules, and their project must be compatible with the configuration's project. When the VM starts, tiCrypt mounts the extra drives in slot order, with Auto drives last. If the hardware setup includes a RAM disk, the form shows its size, and the RAM disk is mounted in slot Z:/23.
The following table describes the errors an extra drive row can show.
| Error | Meaning |
|---|---|
| Not unique | Another row already uses this slot. |
| Drive is used more than once | Another row already uses this drive. |
| Drive is not set | The row has no drive selected. |
| Drive is not writable | The row is Read-write but you cannot write to the drive. Set it to Readonly. |
| Projects incompatible | The row is Read-write but the drive's project is not exactly the configuration's project. |
Share drive keys with co-owners
Each co-owner needs a key to every drive of a configuration to start it. Drive keys are encrypted in your browser, so the server cannot hand them out on its own. Before tiCrypt saves a configuration that has co-owners, it checks which co-owners lack a key and asks you to share it.
A co-owner counts as missing a key when they hold no key to the drive, or hold only a read-only key to a drive the configuration attaches read-write. tiCrypt checks only the drives you can share:
- Ownership: you own the drive, or you are a Sub-admin or above.
- Your key: you hold a read-write key to the drive. A drive that was never formatted has no keys yet; its key is shared with the co-owners when it is first formatted.
- Permissions: you have both the Get drive keys and Share drives permissions.
This procedure describes how to share the missing keys when you save a configuration.
- Click Create or Save in the configuration form.
- In the Share drives with the co-owners of
vm-name? dialog, read the table. It lists each co-owner with the drives they would receive, each marked read-write or read-only. - Click Share and save. To keep the drives private, click Cancel instead. Nothing is saved.
The configuration is saved and the task Share drives with the co-owners of
vm-name gives each listed co-owner a key with the access shown. If you ticked
Launch a VM from this configuration immediately, the VM starts once that task
finishes.
A co-owner who holds a drive key can attach that drive to other VMs. Share a configuration only with colleagues who may see all of its drives.
View a configuration
Clicking a stopped configuration in the left panel opens its detail panel on the right. Clicking a running one opens the running VM panel instead. For more information, see Connect and Access.
The header shows the state dot, the name (followed by "(deleted)" if the configuration was deleted), the operating system, the project tag, the team, and the first two owners, followed by "... and N more" when there are others. Next to it, a state button reflects the configuration's state.
| State | Button | Description |
|---|---|---|
| Stopped | Start VM | Starts the VM. Only owners and co-owners see it. |
| Starting | Starting VM | The VM is starting. |
| Running or Suspended | Stop VM | Opens the shutdown dialog. |
| Stopping | Stopping VM | The VM is shutting down. |
| No connection | No Connection | The VM is running but cannot be connected to. |
The following table describes the cards of the detail panel.
| Card | Contents |
|---|---|
| Hardware setup | The hardware setup's name, description, cores, and memory. A setup in debug mode shows Debug mode in red. |
| Description | The configuration's description, rendered as Markdown. |
| Basic info | Hardware setup, Running VM (when one exists), Project ("None" if untagged), Team, MAC address ("Automatically assigned a MAC address" by default), Host ("Automatically scheduled to run on a suitable host machine" unless a preferred host is set), Last launched and Last ping ("Never" until used), Slurm account and Slurm fairshare (when set), and the configuration ID. |
| Owner or Owners | The owner and every co-owner. |
| Home drive | The home drive with its format and capacity. A drive you can no longer use shows the reason in red. |
| Additional Read-Write Drive(s) | The extra read-write drives, or "This configuration has no additional read-write drives". |
| Additional Read-Only Drive(s) | The extra read-only drives, or "This configuration has no additional read-only drives". |
If the configuration was deleted or is no longer shared with you, the panel reads "This configuration has been deleted or is no longer shared with you."
The toolbar of the detail panel offers these actions:
- Add co-owners: changes who co-owns the configuration. Owners and co-owners only. For more information, see VM Users.
- Edit: opens the configuration form. Owners and co-owners only.
- Bulk email: lists the email addresses of the configuration's owners and co-owners so you can copy or download them.
- Change Project: changes the project tag of a stopped configuration. Requires the Edit any VM configuration permission. For more information, see Projects and Quotas.
- Delete: deletes the configuration. For more information, see Delete a Virtual Machine.
- Power: opens the shutdown dialog while the VM is not stopped. Owners, co-owners, and Super-admins only.
Edit a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, click the menu next to the stopped virtual machine to edit.
- Select Edit.
- In the pop-up, edit the VM name, team, project, VM co-owners, description, hardware setup, and drives. For the rules each field follows, see Configuration form fields.
- Once done, click Save.
- If you removed co-owners, confirm their removal. For more information, see Remove co-owners.
- If the Share drives with the co-owners of
vm-name? dialog appears, click Share and save. For more information, see Share drive keys with co-owners.
The configuration is updated and tiCrypt shows "Updated vm-name". The change takes
effect the next time the VM starts. If you saved without changing anything, tiCrypt shows "No
changes made", unless Launch a VM from this configuration immediately is ticked, in
which case the form closes and the VM starts.
Any owner or co-owner of the configuration can edit it, except while its VM is shutting down. The menu of a running VM shows the running VM's actions instead of Edit, so shut the VM down to edit its configuration. If you open the form while the VM is starting, it warns: "This VM configuration is currently starting or running. Virtual machines are only configured when starting them, so any changes you make will not take effect until you restart the configuration."
Remove co-owners
You remove a co-owner by deleting them from VM Co-owners (optional) in the configuration form, or from the Add co-owners form. Removing a co-owner takes away their access to the configuration. If the VM is running, it also removes them from the running VM.
tiCrypt can also delete the co-owners' keys to the configuration's drives. It offers this only for drives you own, and only if you have the Unshare drives permission. Your own keys are never removed.
This procedure describes how to remove co-owners.
- Open the configuration form with Edit, or open Add co-owners.
- Remove the co-owners from the list of co-owners.
- Click Save in the configuration form, or Update
vm-namein the Add co-owners form. - If the Remove
user-namefromvm-name? dialog appears, leave Also remove their keys to N drive(s) of this configuration ticked (the default) to delete their drive keys, or untick it to let them keep the keys. - Click Remove
user-name.
The dialog appears only if the VM is running or there are drive keys you can remove. Its text depends on the state of the VM:
- Running: "Removing a user from co-owners will completely remove their access to this VM. They have to be added separately if some form of access is desired."
- Stopped: "Removing a user from co-owners will remove their access to this VM configuration. They have to be added separately if some form of access is desired."
The users are no longer co-owners of the configuration. If the VM is running, they are removed from it. If you left the checkbox ticked, their keys to your drives of this configuration are deleted.
A co-owner removed from a running VM loses access to it at once. To give them some other access to the VM, add them again as a VM user.
If a key cannot be removed, tiCrypt shows "Failed to remove the key of user-name to
drive-name", or "Failed to remove N drive keys" when several fail. The user keeps those
keys; remove them from the drive's sharing list. For more information, see
Share Drives.
Delete a Virtual Machine
- Go to the Virtual Machines icon in the top left taskbar.
- Click the VMs section on the top left panel.
- In the left panel, click the menu next to the stopped virtual machine to delete.
- Select Delete.
- In the Delete
vm-name? pop-up, read the warning: "If this VM configuration is shared with other users, it will no longer be accessible. VM configurations can be re-created but will need to be shared again." - Click Delete
vm-name.
The configuration is removed from the VMs list. Its drives are not deleted: they remain in your account and can be attached to another configuration. Deleting a configuration destroys the assembly, never the data.
Any owner or co-owner of the configuration can delete it, and so can a user with the Delete any VM configuration permission. Deleting a configuration removes it for every owner and co-owner, not only for you.