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 window, on the Name and team step, enter a Name and select a Team. Optionally, enter a Description (optional). Click Next.
- On the Project step, optionally select the project to tag the configuration with. Click Next.
- On the Co-owners step, optionally add users to VM Co-owners (optional). Click Next.
- On the Hardware setup step, click the VM hardware setup to allocate resources. To narrow the list, pick a filter such as Filter by Cores or Filter by OS. Click Next.
- On the Drives step, drag a drive from Drives that can be mounted onto Home drive, or click it. To add extra drives, drag or click more drives from the list; each one appears under the home drive, where you can set its slot and access. To use a new drive, click Create new drive to create a new drive. Click Next.
- Optionally, on the Advanced step, enter a MAC Address (optional) or choose a Preferred host to start VM on. Click Next.
- On the Review step, check the configuration. Leave 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.
If the hardware setup includes a RAM disk, the Drives and Review steps show "A RAM disk of size will be mounted in slot Z:/23."
Configuration form fields
The configuration form is the same for creating and editing. It is a step-by-step form in a large
window. Its title is Create new VM configuration when you create one and Update
vm-name when you edit one. The steps are, in order, Name and team, Project,
Co-owners, Hardware setup, Drives, Advanced, and Review. Project,
Co-owners, and Advanced are marked optional.
The form checks each step before it lets you go on. Next stays disabled while a field of the current step is invalid, and a step with a problem shows its error under its name, such as "Name and team are required." When you create a configuration, you reach a step only through the steps before it. When you edit one, every step has already been completed, so you can click any step name to go straight to it, up to the first step that has a problem. Previous goes back one step, and Cancel closes the form without saving.
Changing the project or the hardware setup sends you back to the Drives step. The project and the hardware setup decide which drives the VM can use and on which host it can start. When you change either one, tiCrypt removes the drives that no longer fit, makes extra drives read-only where they can no longer be written, resets a preferred host from another realm to Any host (scheduled), and marks the Drives step and every step after it as not yet visited, so you review them again.
The following table describes the fields of each step.
| Step | Field | Required | Description |
|---|---|---|---|
| Name and team | Name | Yes | Up to 80 characters. The name must differ from every other configuration you can see. |
| Name and team | Team | Yes | The team that owns the configuration. Only teams you belong to are offered. |
| Name and team | Description (optional) | No | Up to 250 characters. Markdown is supported. |
| Project | Project list | No | The project tag, picked from a list of projects with a Filter projects... box. 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. |
| Co-owners | VM Co-owners (optional) | No | Other users who co-own the configuration. You are always its owner, so you are not offered. |
| Hardware setup | Hardware setup list | Yes | Determines what software gets loaded and what hardware resources the VM has access to. See Choose a hardware setup. |
| Drives | Home drive | Yes | The first drive of the VM, which holds the VM's user database and home directories. |
| Drives | Extra drives | No | Further drives, each with a slot and an access type. See Choose the drives. |
| Advanced | MAC Address (optional) | No | 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. Once a configuration has a MAC address, the field is labelled MAC Address and cannot be emptied: "A MAC address can't be removed once assigned". |
| Advanced | Preferred host to start VM on | No | 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. |
| Review | Launch a VM from this configuration immediately | No | Starts the VM once the configuration is saved. Ticked by default when you create a configuration, unticked when you edit one. Not shown while the configuration's VM is starting or running. |
A name may not contain any of the characters / \ | " : * ? < > { } or NUL. A description may not
contain < > { }.
The Review step shows the whole configuration before you save it: the VM with its hardware setup, the home drive and every extra drive with its access and slot, and cards for Team, Description, Project, Co-owners, Hardware setup, and Advanced options (the MAC address and, when hosts are listed, the preferred host). Create or Save is on this step.
Choose a hardware setup
The Hardware setup step lists the hardware setups you can use. Each row shows the setup's name, its realm, its cores and memory, and its devices. A red icon marks a setup in debug mode, and selecting one shows "This hardware setup enables administrators to access the VM remotely for debugging." A setup whose image is missing shows "· Missing image" (or "No image", "Missing image volume") in red and cannot be picked; hovering over it tells you why VMs can't start from it.
The filter selector above the list narrows it by one property at a time:
| Filter | Choices |
|---|---|
| Filter by Name | Search hardware setups..., a text search on the name. |
| Filter by Cores | All Cores, or At least a number of cores. |
| Filter by Memory | All Memory, or At least an amount of memory. |
| Filter by Devices | All Devices, or With a device type. Offered only when a setup has devices. |
| Filter by OS | All, Windows, or Linux. |
| Filter by Realm | All Realms, or one realm. Offered only when the setups span more than one realm. |
The list works from the keyboard: the arrow keys move between setups, and Enter or Space selects one.
Choose the drives
The Drives step has two sides. Drives that can be mounted lists your drives that the configuration can use, and the other side shows the VM with its Home drive and its extra drives. Until you select a hardware setup, the list reads "Select a hardware setup before choosing drives."
- Home drive: drag a drive onto Home drive, or click it in the list, or select it and press Enter or Space. While there is no home drive, the first drive you pick becomes the home drive. To change it, click Remove home drive next to it and pick another.
- Extra drives: once there is a home drive, drag a drive onto the drive area or click it to attach it as an extra drive. Each drive can be added once, and a drive already added is no longer listed.
- Slot: each extra drive has a slot selector: Auto, or a slot from E:/2 to Y:/22. Two drives cannot use the same slot.
- Access: each extra drive has Read-write or Readonly. A drive starts as Read-write when you can write to it and its project is exactly the configuration's project, and as Readonly otherwise.
- Remove: Remove drive from list takes an extra drive off the configuration.
- Create new drive: creates a drive with the configuration's team and project and adds it, as the home drive when there is none yet, otherwise as an extra drive.
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 Drives step shows its size, and the RAM disk is mounted in slot Z:/23.
If no drive meets the home drive rules, the list shows "No drives can be used as the main drive" followed by the realm and project it needs and the formats the hardware setup accepts. Create a matching drive with Create new drive, or pick another hardware setup.
Next on the Drives step stays disabled while there is no home drive, two extra drives share a slot, or an extra drive set to Read-write cannot be written by you or does not carry exactly the configuration's project. Set such a drive to Readonly, change its slot, or remove it.
Changing the hardware setup re-checks the drives. Another setup can be in another realm or accept
other formats. If the new setup cannot use the selected home drive, the home drive is removed and you
pick another, and extra drives the new setup cannot use are taken off the list. A drive made with
Create new drive that the selected setup cannot use is not added: tiCrypt shows "Created
drive-name, but the selected hardware setup can't use it (other realm or format)", and the
drive stays in your drive list.
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. Greyed out, with the reason, for users who may not shut the VM down; see the Power action below. |
| 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. |
| Network access | Shown when a VM access rule names the configuration. Each rule shows its name, protocol, server, and ports, followed by Always allowed, or by Open access and Close access for a time-limited rule. See Open network access for a VM. |
| 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. Everyone who sees the configuration sees it, but it is greyed out, with the reason in its tooltip, while the VM is starting ("the VM is still starting") or shutting down ("the VM is already shutting down"), and for users who may not shut the VM down. For who may, see Shut Down a Virtual Machine.
- Open access: rule name: opens network access for the VM on a time-limited VM access rule that names the configuration. Shown once per such rule. For more information, see Open network access for a VM.
Open network access for a VM
A VM access rule lets the VMs of chosen VM configurations reach one server outside tiCrypt, such as a license server, on given ports. Secure VMs have no outbound network access otherwise. A Super-admin creates the rules; you see the ones that name your configuration in its Network access card. A rule is either always open, shown as Always allowed, or time-limited: closed until a user opens it for one configuration, for a number of minutes up to the rule's maximum. Access rules need backend 3.16.0 or later. For how the rules work, see Dynamic Firewall Rules, and for how admins manage them, see VM Access Rules.
This procedure describes how to open access on a time-limited rule.
- Select the configuration in the VMs list.
- Click Open access next to the rule in the Network access card, or select Open access: rule name in the configuration's ⋮ menu.
- In the Open access: rule name dialog, check the VM configuration, and enter the Access time (minutes). The field starts at 60, or at the rule's maximum if that is lower, and its hint reads "Up to N minutes for this rule."
- Click Open access.
tiCrypt shows "Opened access". The VMs of the configuration can reach the rule's server on its ports until the time runs out.
To end access early, click Close access next to the rule, then Close access in the dialog. "Closing access takes effect immediately. It is safe to close access that is already closed." tiCrypt shows "Closed access".
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 Update
vm-namewindow, click the name of the step to change, such as Drives, or move through the steps with Next. For the rules each field follows, see Configuration form fields. - On the Review step, check the configuration and 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.
Only the running VM's Owner can take a co-owner off the running VM. On the running VM a co-owner
is a manager, and the server lets only the VM's Owner, the user who started it, remove managers. If
another co-owner removes them, the configuration is still saved: they are no longer co-owners of the
configuration, the drive keys are revoked as you chose, and the users are synchronized. tiCrypt then
shows "user-name was removed as a co-owner of vm-name, but stays on its
running VM until the VM's owner removes them". Ask the VM's Owner to remove them from the VM. For
more information, see Remove Users from a Virtual Machine.
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.