tiCrypt 2.18.1

Create and Manage Drives

An encrypted drive is a virtual disk whose contents are encrypted with a key held by you, not by the server. A drive is not a folder in the Vault. The Vault stores individual encrypted files that you upload and download one at a time; a drive is a block device that a virtual machine mounts as an ordinary filesystem and writes to directly. Drives are the only thing that carries your data from one VM session to the next.

Why data lives on drives rather than in the VM

A virtual machine resets on every restart. tiCrypt VMs boot from a clean image, so nothing written to the guest operating system survives a shutdown. That is a deliberate defence against persistent malware, but it means a machine on its own has nowhere to keep your work. A drive is the piece that persists.

Software needs a filesystem, not a file store. Analysis tools open, seek, and append to files using ordinary system calls. They cannot work against a store that requires an explicit upload-and-download step. Mounting a drive gives applications a normal filesystem while the contents stay encrypted at rest, so no tool needs to be aware of tiCrypt at all.

The format is a permanent decision. A drive's format determines which machines can mount it: NTFS for Windows, and EXT4 or BTRFS for Linux. These are the three formats you can choose when you create a drive; existing drives can also be XFS or ZFS, which are Linux formats. You cannot reformat a drive to move it between operating systems, and NTFS drive names cannot be changed after creation because Windows BitLocker ties the encryption to the device and its name. Choose the format and the name for the machine you intend to run, not the one you are running today.

The first attached drive is special. The first drive attached to a configuration is the home drive, and it carries the VM's user database. Accounts, roles, and permissions travel with it, so moving a home drive to another configuration brings its users along. See VM Roles and Permissions.

Where drives appear inside the VM

Drives are mounted under /drives/. The first drive attached to a configuration is mounted at /drives/drive1 and is the home drive. Every drive also carries a symlink named after the drive itself, so a drive named lab-data is reachable at /drives/lab-data.

Numbers are assigned as drives are attached, and detaching a drive does not renumber the ones that remain. Both paths are stable, so either works in a script; prefer the name in anything you write down or share, because it says which drive you meant.

Drives can be attached to and detached from a VM while it is running. That is a different operation from editing the configuration, which requires the VM to be stopped.

This is the path that matters for any script you write. A job that writes its output anywhere outside /drives/ writes to the guest filesystem, which is discarded when the machine stops. Batch jobs are the common case: worker VMs are destroyed when the job ends, so results left outside /drives/ are gone before you read them.

The mount is performed by the VM Controller at boot rather than through /etc/fstab, which is why a drive appears without any entry in the image. The slot a drive is assigned is also shown under Extra drives (optional) when you create the VM.

Before you begin

• You have the Create drives and Get drive keys (needed to share and attach drives) permissions.
• You know which operating system will mount the drive, because the format cannot be changed later.
• Your team has storage quota remaining. Drive capacity is drawn from the team allocation.

Create a New Drive

Method One

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Drives section on the top left panel.
3. Click the New Drive button at the top of the left panel.
4. In the Create new drive prompt, enter the drive name and capacity in GB or TB.
5. Select the drive format from:
   EXT4 (Linux)
   BTRFS (Linux)
   NTFS (Windows).
   
6. Add an optional owner, team, optional project, and realm.
7. Click Create.

Result:

tiCrypt shows "Created drive" followed by the drive name, and the drive appears in the Drives list. The drive has no encryption key until it is first attached and formatted; see Format and encrypt a drive on first use.

Method Two

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Virtual Machines section on the top left panel.
3. In the left panel, select the virtual machine to create a new drive in.
4. Click the VM Settings and Details option in the bottom center.
5. In the new window, select the Drives section in the left panel.
6. Click Attach drive(s) icon in the top panel.
7. In the prompt, select Create a new drive.
8. In the prompt, enter the drive name and capacity in GB or TB.
9. Select the drive format from:
   EXT4 (Linux)
   BTRFS (Linux)
   NTFS (Windows).
   
10. Add an optional owner, team, and realm. The project is locked to the VM's project, and the prompt shows "Project locked to ensure compatibility with the VM."
11. Click Create.
12. Back in the Attach drive(s) to vm-name prompt, the new drive is added as a Read-write row. Click Attach and mount to attach it.

note

• Your drive capacity depends on your allocated team resources.
• Your drive format determines what kind of VM the drive can be attached to.
• Click the Advanced Options button to set the permission management status and the Cache & IO strategy for the drive.

The following table describes the fields of the Create new drive prompt.

Field	Description
Name	Up to 80 characters. It cannot contain slashes, backslashes, pipes, double quotes, colons, asterisks, question marks, angle brackets, or curly braces, and must differ from the names of the drives you can access ("Conflicts with another drive").
Capacity	The size in GB or TB. The realm can set a minimum and a maximum size ("Minimum size for this realm is", "Maximum size for this realm is").
Format	EXT4 (Linux), BTRFS (Linux), or NTFS (Windows). Required ("You must select a type for the drive").
Drive owner (optional)	The user who owns the drive. Leaving it blank makes you the owner.
Team	One of your teams. Required. The drive's capacity counts against this team's storage quota.
Project	Optional. The project tag of the drive.
Realm	Optional. The realm the drive is created in.
Backup settings	Never back up this drive or This drive may be backed up. Shown only when drive backup tracking is enabled on your deployment, and selectable only for a Libvirt realm.
No permission management (Advanced Options)	Enable or Disable. See the warning below.
BTRFS compression algorithm (Advanced Options)	Shown for BTRFS drives. ZLIB (slower, higher compression ratio), LZO (faster compression and decompression than zlib, worse compression ratio), or ZSTD (compression comparable to zlib with higher speeds). For ZLIB and ZSTD, Compression level sets a level from 1 (fastest, least compressed) to 9 (slowest, most compressed); the default is 3.
Cache Strategy and IO Strategy (Advanced Options)	Use value from realm configuration (default), or a specific strategy. See Drive Details.
Libvirt Pool (Optional) (Advanced Options)	Shown for a Libvirt realm once a team is selected. Each pool shows the space your team has available in it.

For a Libvirt realm, the capacity is also checked against the selected pool: "You do not have access to this drive pool", or "Exceeds the quota for the selected team" followed by the space remaining. If no pool has room within your team's quota, the prompt shows "No space available on any pool due to quota restrictions." and Create stays inactive.

Confirmations, Errors & Solutions

Created Drive Successfully

Created drive drive-name.

Selected NTFS (Windows) Drive Format

NTFS drive names cannot be changed after creation due to Windows BitLocker restrictions. The encryption is tied to the device and its name. Please be cautious and choose drive names carefully during the creation process.

Did Not Select Optional Drive Owner

Leaving this blank means you will be the owner.

Enabled No Permission Management

In Create new drive prompt, under Advanced Options you selected Enable option.

If you select this option, tiCrypt will not manage permissions for this drive. No access directories can be created on the drive and the data is not available to regular users. This option is useful if you want applications such as databases to store their data on the drive.

Did Not Enter Drive Name

You must enter a name.

Enter Drive Name

In the Create new drive prompt, enter the drive name in the Name field.

Did Not Enter Drive Capacity

You must enter a capacity for the drive.

Enter Drive Capacity

In the Create new drive prompt, enter the drive capacity in the Capacity field.

Did Not Select Drive Team

You must select a team from the autocomplete.

Select Drive Team

In the Create new drive prompt, under Relation section, enter the drive team in the Team field.

Unable to Select Backup Settings

Your back-up settings are inactive upon drive creation.

Select Libvirt Realm

In the Create new drive prompt, in the Realm field, select a Libvirt realm.

Unable to Create Drives

Drive creation failed: Unable to perform action, missing permissions.

Ask Admin for Drive Creation Permissions

Ask your admin to allow you to create drives.

To Admin

To allow a user to create drives:

1. In the Management section, click the Users section in the left panel.
2. Select the appropriate user to update permissions.
3. Click the Open overlay button in the top right.
4. In the new window, go to the Manual permission management section.
5. Under Virtual Machines section, tick the Create drives permission.
6. Once done, click Save in the top center.

Create Drive Button Inactive

No space available on any pool due to quota restrictions.

Complete the Form or Ask for More Team Quota

The Create button in the Create new drive prompt stays inactive until the Name, Capacity, format, and Team fields are valid and the selected team has space left on a drive pool.

To Admin

To increase the team quota follow the steps in  

Edit Teams' Quotas.

Attach an Existing Drive to an Existing VM

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Virtual Machines section on the top left panel.
3. In the left panel, select the virtual machine to attach the drives to.
4. Click the VM Settings and Details option in the bottom center.
5. In the new window, select the Drives section in the left panel.
6. Click Attach drive(s) icon in the top panel.
7. In the prompt, select Add a new drive.
8. Next, select the drive and the drive type: Readonly or Read-write.
9. Leave the Add drive(s) to the VM configuration and share drive(s) with co-owners box ticked (the default), or untick it if the drive should not be attached and mounted again when the configuration restarts.
10. Click Attach and mount.

Result:

The task Attach/mount drive-name to vm-name runs for each drive. A drive you hold no key for is formatted first; see Format and encrypt a drive on first use.

info

• A read-write drive can only be attached to a single VM. A read-only drive can be attached to multiple VMs.
• To automatically share the newly created or attached drive with the VM co-owners, keep the Add drive(s) to the VM configuration and share drive(s) with co-owners box ticked. It is ticked by default. When you untick it, the prompt warns: "Not adding drive(s) will not automatically attach and mount to the VM when the configuration is restarted."
• You can also open this prompt from the VM's File Explorer: click Attach/mount drives above the folder tree.

Who can attach drives. Only the VM Owner or a co-owner of its configuration can attach drives. Anyone else gets "Only the (co)owner of a VM can attach drives to it" followed by the name of the Owner. If the VM has no configuration, the drives are attached but not recorded, and tiCrypt shows "This VM has no configuration to record the drives in".

Which drives are offered. The Drive list offers drives in the same realm as the VM, compatible with the VM's project, and in a format the VM can mount. The home drive is not offered.

The prompt marks these problems on a row:

• Drive is not set: The row has no drive selected.
• Drive is used more than once: The same drive appears in two rows.
• Drive is not writable: The drive cannot be attached Read-write. Choose Readonly.
• Projects incompatible: The drive's project differs from the VM's, so it cannot be attached Read-write.

If you click Attach and mount with no rows, tiCrypt shows "You have not selected any drives to attach".

Confirmations, Errors & Solutions

Attached Drive Successfully

Attach/mount drive-name to vm-name(total-attaching-time).

Unable to Attach Drive

Failed at attaching-time: cannot format/encrypt read-only drive: drive-name.

If the drive is re-attached read-only or read-write, the following error appears in the prompt.

Timeout Failure to Attach Drive

Failed at attaching-time: Timeout waiting for item drive-string-id to satisfy predicate.

Detach the Drive from the Other VM

tiCrypt waits up to 60 seconds for the drive to be free for the requested attachment, then fails with this error. A drive attached read-write to another VM cannot be attached anywhere else, and a drive attached read-only to another VM cannot be attached read-write.

To Drive Owner

Detach the drive from the other VM, then attach it again. To detach a drive follow the steps in  

Detach a Drive from an Existing VM.

Missing Permissions To Attach/Mount Drive

First attempt to attach/mount home drive failed (will retry once): Unable to perform action, missing permissions.

Ask Admin to Allow You to Attach/Mount Drives

Ask your admin to update your permissions for attaching and mounting drives.

To Admin

To update drive attach/mount permission for a user:  

1. Go to the Management icon in the top left taskbar.
2. Navigate to the Users section.
3. Click the Users in the top left panel.
4. Select the user whose permissions you want to update.
5. Click the Open full menu button in the top right panel.
6. Select Open overlay.
7. In the new window, navigate to Miscellaneous.
8. Click Manual permission management in the left panel.


9. Under Virtual Machines, tick the following permissions.
View their drives
Get drive keys (needed to share and attach drives)
Attach drives to VMs
Detach drives from VMs
10. Once done, click the Save button above.

Format and encrypt a drive on first use

A new drive has no encryption key until it is formatted. Whenever you attach or mount a drive you hold no key for, tiCrypt offers to format it and create a new key. This happens on any path that mounts a drive: Attach and mount, Remount drive(s), Mount all Drives, the Repair notice, and starting a VM. If the drive is already in use by someone else, ask its owner to share it with you instead of formatting it.

Formatting erases the drive. For a drive that has never been attached, that loses nothing, so the prompt only asks for confirmation. For a drive that has been attached to a VM before, it may destroy data, so the prompt asks you to type the drive's name.

1. Attach or mount the drive, for example with Attach and mount.
2. In the Format/encrypt drive-name? prompt, review the drive information table (format, capacity, creation date, team, project, owner, and state).
3. If the prompt says "This drive has been previously attached to a VM and may contain data.", type the drive's name exactly in the Type to Confirm field. Matching is case-sensitive. A new drive's prompt ("For new, uninitialized drives, formatting is required before use in a VM.") does not ask you to type anything.
4. Click Format followed by the drive name.

Result:

tiCrypt generates a new encryption key, the VM controller formats and mounts the drive, and the read-write key is uploaded to tiCrypt. The key is then shared with the co-owners of the VM's configuration.

Formatting a previously used drive erases its data

The prompt warns: "Formatting will erase all data. Ensure no important data remains before proceeding. If unsure, contact an administrator". If you are not certain the drive is empty, cancel and ask the drive owner.

The following errors can stop formatting:

• "cannot format/encrypt read-only drive:" followed by the drive name: A drive attached Readonly cannot be formatted. Attach it Read-write for its first use.
• "Drive drive-name is currently being formatted. Please wait for the current formatting process to complete before attempting to format again.": A format of this drive is already running in your session. Wait for it to finish.

Remount an Existing Drive in an Existing VM

bulk-action

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Virtual Machines section on the top left panel.
3. In the left panel, select the virtual machine to remount the drive into.
4. Click the VM Settings and Details option in the bottom center.
5. In the new window, select the Drives section in the left panel.
6. Select the drive(s) to remount. Every selected row must have the Type Unmounted or Unattached.
7. Click the Remount drive(s) icon in the top panel.

Result:

Each drive is attached and mounted again with its previous access. A RAM disk or NFS row is re-created instead.

note

Remount drive(s) is offered to Managers and higher who hold the VM's Drives permission and the system permission Attach drives to VMs.

Mount All Existing Drives in an Existing VM

bulk-action

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Virtual Machines section on the top left panel.
3. In the left panel, select the virtual machine to mount all drives into.
4. Click the VM Settings and Details option in the bottom center.
5. In the new window, select the Drives section in the left panel.
6. Click Mount all Drives icon in the top panel.

Result:

The task starts immediately, without a confirmation prompt. It runs the same steps as starting the VM: it checks the home drive, then attaches and mounts every drive of the configuration that is not mounted.

note

Mount all Drives is offered to Managers and higher, and only when the VM has a configuration.

Confirmations, Errors & Solutions

Mounted All Drives Successfully

Mount all drives on vm-name? (total-mounting-time).

Timeout Failure to Mount All Drives

Failed at mount-all-attaching-time: Timeout waiting for item drive-string-id to satisfy predicate.

Ask Drive Owner(s) to Change All Drive Types To Ready

Ask the drive owner(s) to change all drives in the VM to a ready state.

To Drive Owner
A drive in the ReadOnly or ReadWrite state is attached to a VM. Detaching it from the other VM returns it to Ready, after which you can mount all drives again.

To detach a drive follow the steps in  

Detach a Drive from an Existing VM.

Detach a Drive from an Existing VM

1. Go to the Virtual Machines icon in the top left taskbar.
2. Click the Virtual Machines section on the top left panel.
3. In the left panel, select the virtual machine to detach the drive from.
4. Click the VM Settings and Details option in the bottom center.
5. In the new window, select the Drives section in the left panel.
6. From the list, select the drive you want to detach. Every selected row must have the Type Mounted; the Home drive cannot be detached.
7. Click the Open full menu button in the top right panel.
8. Select Detach drive(s).
9. In the Do you want to detach drive drive-name from vm-name? prompt, click Yes to proceed.

Result:

The drive is unmounted and detached from the running VM. It stays in the VM configuration, so it is attached and mounted again the next time the configuration starts.

warning

Detaching a drive revokes user access and stops applications running from the drive.

note

Detach drive(s) is offered to Managers and higher who hold the VM's Drives permission and the system permission Detach drives from VMs.

Detach a Drive and Remove It from the VM Configuration

Detach drive(s) only affects the running VM. To stop a drive from coming back when the configuration restarts, use Detach and remove.

Location: Virtual Machines > Virtual Machines > select the virtual machine > VM Settings and Details > Drives

1. Select the drive(s) to detach. Every selected drive must be Mounted and part of the VM configuration, and none can be the home drive.
2. Click the Open full menu button in the top right panel.
3. Select Detach and remove.
4. In the Do you want to detach and remove drive drive-name from vm-name? prompt, which adds "The drive will also be removed from the VM configuration.", click Yes.

Result:

tiCrypt shows "Drive drive-name successfully detached and removed from the VM configuration".

note

Detach and remove is offered only to owners of the VM configuration (its creator and co-owners), with the same permissions as Detach drive(s).