> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared VM storage for Orka CI artifacts

> Mount a shared storage volume across Orka VMs for CI artifact caching. Deprecated on Apple silicon Monterey; available for Intel and Apple silicon Ventura+.

| Platform                               | Status                                                                                  | Notes                               |
| -------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- |
| Apple silicon, macOS Monterey          | Removed as of Orka 3.0                                                                  | Intel Monterey VMs are not affected |
| Intel, macOS Monterey                  | Supported                                                                               |                                     |
| Apple silicon, macOS Ventura and later | Supported as of [Orka 3.0](/orka/orka-upgrades-and-release-notes/orka-30-release-notes) | Requires Orka VM Tools              |
| Intel, macOS Ventura and later         | Supported                                                                               |                                     |

<Note>
  **Orka 3.5 default change:** Shared VM storage is disabled by default for new Orka deployments. Existing deployments retain the previous setting (enabled). To enable shared storage on a new deployment, open a support ticket.
</Note>

<Note>
  **Orka 3.5.2:** Per-instance shared attached disk sizing is now supported. On AWS, set `VM_SHARED_DISK_SIZE` in each instance's user data script. On-prem, set `osx_node_orka_vm_shared_disk_size` via Ansible. See the [Orka 3.5.2 release notes](/orka/orka-upgrades-and-release-notes/orka-35-release-notes) for full setup steps.
</Note>

## Overview

Starting with Orka 1.6.0, all deployed Intel-based VMs will have access to a shared storage volume in the cluster. Starting with Orka 2.1.0, all deployed ARM-based VMs will have access to the same shared storage.

This storage can be used to cache build artifacts in-between stages of your CI/CD pipeline, for example, or host Xcode installers and other build dependencies.

Orka offers two different ways to utilize shared VM storage:

1. By default, the VM shared storage directory will be placed on the primary NFS storage export for your cluster. This means that VM shared storage will share storage space with VM images and ISOs, so please keep this in mind!
2. Optionally, you may request to provision a secondary storage export that will be dedicated to shared storage. This is ideal if you plan to share a lot of data between your CI/CD pipeline builds.

## Shared Storage in ARM-based VMs

In ARM-based VMs the shared storage will be automatically mounted and available to use. Same storage is shared between ARM-based and Intel-based VMs.

<Note>
  To use the shared VM storage with VMs deployed on ARM nodes, make sure to pull the new sonoma-90gb-orka3-arm image from the remote. It contains Orka VM Tools which are required for the shared VM storage to be automounted in the VM.

  [Learn more about pulling an image](/orka/orka3-cli-reference/image-management)
</Note>

## Shared Storage in Intel-based VMs

```
sudo mount_9p orka
```

The volume will be mounted at /Volumes/orka. The first time you attempt to access the filesystem via Terminal, you will be asked to grant the Terminal application permissions to access files on a network volume:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28340384462491.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=588c49333c6c242da4ddcbb527920b2a" alt="macOS prompt requesting Terminal access to network volume" width="359" height="311" data-path="images/attachments/28340384462491.png" />

Click the OK button to allow access. You will then be able to access files on the volume:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28340339123227.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=3e0dd36492282916b717c8d3be7794e5" alt="Terminal showing /Volumes/orka mounted and accessible" width="635" height="434" data-path="images/attachments/28340339123227.png" />

## Automount shared storage in Intel-based VMs

Instead of mounting the shared storage manually after every OS restart, you can create a /Library/LaunchDaemons/com.mount9p.plist to handle automounting the shared storage.

1. Connect to your VM via SSH.

```
     ssh <macOS_user>@<VM_IP> -p <SSH_PORT>
```

2. Make sure that /Volumes/orka is already mounted on the VM.

```
     ls /Volumes
```

3. If not already mounted, mount the shared VM storage.

```
     sudo mount_9p orka
```

4. Navigate to /Library/LaunchDaemons and create a com.mount9p.plist file.

```
     cd /Library/LaunchDaemons  
       
     ls  
       
     sudo vim com.mount9p.plist
```

5. Copy the following contents and paste them in Vim. Type :wq to save and exit.\
   com.mount9p.plist

```
     <?xml version="1.0" encoding="UTF-8"?>  
     <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  
     <plist version="1.0">  
     <dict>  
     <key>Label</key>  
     <string>com.mount9p.plist</string>  
     <key>RunAtLoad</key>  
     <true/>  
     <key>StandardErrorPath</key>  
     <string>/var/log/mount_9p_error.log</string>  
     <key>StandardOutPath</key>  
     <string>/var/log/mount_9p.log</string>  
     <key>ProgramArguments</key>  
     <array>  
     <string>/bin/bash</string>  
     <string>-c</string>  
     <string>mkdir -p /Volumes/orka && mount_9p orka</string>  
     </array>  
     </dict>  
     </plist>
```

6. Change the ownership and permissions for com.mount9p.plist.

```
     sudo chown root:wheel /Library/LaunchDaemons/com.mount9p.plist  
     sudo chmod 600 /Library/LaunchDaemons/com.mount9p.plist
```

7. Reboot the VM and save or commit the VM image.

## Limitations

### Reading and Writing Data

You may encounter permissions issues when reading or writing data to the shared storage volume. In order to get around this, you may need to become the root user to write data to the shared storage volume.

If you need to give a specific user read and write access to files, you can add that user to the group 107. For example, if your CI user is called machine-user create the group ci:

```
sudo dscl . create /Groups/ci  
sudo dscl . create /Groups/ci gid 107  
sudo dscl . create /Groups/ci passwd '*'  
sudo dscl . create /Groups/ci GroupMembership machine-user
```

Confirm the above changes were made with the command dscl . read /Groups/ci. Reboot the virtual machine and save or commit the VM image to persist these changes.

<Note>
  Files must be given group write access to be modified by the user you have added to the 107 group. For example, `sudo chmod g+w myfile.txt`.
</Note>

### Cluster storage limits

If you are using the default primary storage export in your cluster for shared VM storage, keep in mind that this storage is also used to host your Orka VM images and other data. This should be acceptable for sharing a limited set of files between virtual machines but is not recommended for intensive IO. In the case that you require frequent use of multiple reads and writes to the shared storage volume, setting up dedicated secondary storage is highly recommended.

## Known Issues

When connecting to the VM over SSH and attempting to access the shared storage volume, you may encounter the error orka: Operation not permitted:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28340339125531.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=a2bf55e226963c25777ceb194bb6a2f1" alt="Terminal showing &#x22;orka: Operation not permitted&#x22; SSH error" width="643" height="137" data-path="images/attachments/28340339125531.png" />

To fix this issue, connect to the VM via VNC and navigate to System Preferences → Security & Privacy and click the Privacy tab. From the list select Full Disk Access and click the padlock in the lower lefthand corner to make changes:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28340384468251.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=0cdb0aa2b44232650a973e14f265b476" alt="macOS Security and Privacy Full Disk Access settings with padlock" width="693" height="619" data-path="images/attachments/28340384468251.png" />

You will then be prompted to enter your password. Next, click the checkbox next to sshd-keygen-wrapper:

<img src="https://mintcdn.com/macstadiuminc/9E4UGn8KwDOik0d3/images/attachments/28340339129371.png?fit=max&auto=format&n=9E4UGn8KwDOik0d3&q=85&s=5736d94792da90536a6b42e20a7c7ece" alt="Full Disk Access list with sshd-keygen-wrapper checkbox selected" width="692" height="614" data-path="images/attachments/28340339129371.png" />

Click the padlock again to prevent further changes. You should now be able to access the shared storage volume over an SSH connection.

**IMPORTANT**

Make sure to save or commit the VM image after completing the above steps to persist changes.